2단계. 상품 목록 조회

Hive Axyl 서버에 등록된 Steam 상품의 상품명, 가격, 통화 등을 조회합니다. 사용자에게 현재 판매할 수 있는 최신 상품 목록과 정확한 가격을 표시할 때 사용하세요.

아래 과정을 따라 Steam 상품 정보를 조회합니다.

1. Steam 사용자 ID(StorePlayerId) 획득

Steam 결제 상품을 조회하려면 먼저 사용자의 Steam 64비트 SteamID를 획득해야 합니다. 이 값은 이후 단계에서 StorePlayerId로 사용됩니다.

Steamworks.NET의 SteamUser.GetSteamID()를 호출해 현재 로그인한 Steam 사용자의 64비트 SteamID를 가져옵니다.

Unity

using Steamworks;

// SteamAPI.Init()가 호출된 상태에서 Steam 사용자 ID를 획득합니다.
CSteamID steamId = SteamUser.GetSteamID();
long storePlayerId = (long)steamId.m_SteamID;

SteamAPI.Init()가 호출되지 않은 상태에서는 유효한 SteamID를 얻을 수 없습니다. 1단계. 연동 환경 구성에서 안내한 Steamworks 초기화 전제 조건을 충족했는지 확인하세요.

2. 상품 상세 정보 조회

Hive Axyl 서버에 등록된 Steam 상품의 상세 정보를 조회합니다. 조회한 상품 정보를 사용자에게 노출하세요.

FetchSteamProductsAsync

Steam 상품 목록 조회를 구현하려면 Hive Axyl SDK가 제공하는 FetchSteamProductsAsync()를 호출하세요. 이 호출은 Steam 계정 연동 검증, GetUserInfo, 차단 확인을 내부에서 수행한 뒤 사용자의 통화 기준 상품 목록을 서비스 표준 형식(Single Standard)으로 반환합니다. 별도의 구매 사용자 정보 조회 호출은 필요하지 않습니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	ProductSteam	Required	조회 조건(상품 유형·마켓 등)을 담은 요청 데이터입니다.
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 멱등키·취소 토큰·요청 정책을 지정하며, 생략하면 기본값이 사용됩니다.

ProductSteam

필드명	타입	필수 여부	설명
`AppVersion`	string	Optional	앱의 현재 빌드 버전을 문자열로 전달합니다. 예: `1.0.0`
`Language`	string	Required	상품 이름 등 현지화에 사용할 언어 코드(ISO 639-1 두 자리)입니다. 예: `ko`
`ProductType`	string	Optional	상품 유형입니다. 예: `consumable`
`ProviderId`	ProductSteamProviderId (enum)	Required	마켓 식별자입니다. Steam 상품 조회 전용 요청이므로 `Steam`만 지정합니다.
`ServerId`	string	Optional	Hive 콘솔 앱 서버를 따라 `앱 정보 > 앱 서버`에서 앱 서버를 등록한 뒤 앱 서버 탭에서 확인하는 서버 ID입니다. 예: `server01`
`StorePlayerId`	long	Required	Steam 64비트 SteamID입니다. Steam이 사용자 국가와 통화를 확인하는 데 사용합니다.

호출 예시

PaymentsFetchSteamProductsResult의 성공 결과와 이 메서드에서 정의한 도메인별 결과(Outcome)는 아래 예시와 응답 상태에서 확인합니다. 요청 수행이 불가능한 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

Unity

using Hive.Axyl.Payments;
using Hive.Axyl.Core;

// payments: 초기화 시 등록된 IPaymentsService (자세한 획득은 [모듈 설치 및 초기화](../init.md) 참고)
IPaymentsService payments = HiveCore.Resolve<IPaymentsService>();

// 조회 조건을 담은 요청 객체를 생성합니다.
var request = new ProductSteam
{
    ProductType = "consumable",
    ProviderId = ProductSteamProviderId.Steam,
    Language = "ko",
    StorePlayerId = storePlayerId
};

PaymentsFetchSteamProductsResult result = await payments.FetchSteamProductsAsync(request);

switch (result)
{
    case PaymentsFetchSteamProductsResult.Success success:
        // 표준 형식으로 정제된 상품 목록으로 상점 화면을 구성합니다.
        foreach (var product in success.Data.Products)
        {
            Debug.Log($"{product.ProductId}: {product.Title} ({product.DisplayPrice})");
        }
        break;

    // 요청 검증 실패 결과(Outcome) 처리
    case PaymentsFetchSteamProductsResult.PaymentBadRequest:
    case PaymentsFetchSteamProductsResult.PaymentInvalidParameter:
        // 요청 필드와 필수값을 점검하세요.
        break;

    // 공통 Failure 처리
    case PaymentsFetchSteamProductsResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 처리하지 않은 결과 및 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 PaymentsFetchSteamProductsResult.Success의 Data(ProductResponseData)에 결과가 담깁니다.

필드명	타입	필수 여부	설명
`Data.AppVersion`	string	Optional	앱 버전입니다.
`Data.Country`	string	Optional	국가 정보입니다.
`Data.Currency`	string	Optional	통화입니다.
`Data.Language`	string	Required	언어입니다.
`Data.Products`	IReadOnlyList<ProductProducts>	Optional	표준 형식으로 정제된 상품 정보 목록입니다.
`Data.ProviderId`	ProductProviderId (enum)	Required	마켓 식별자입니다. 이 응답에서는 `Steam`이 반환됩니다.
`Data.Meta`	string	Optional	응답 메타 정보입니다. 없으면 `null`입니다.

ProductProducts

필드명	타입	필수 여부	설명
`Currency`	string	Optional	통화입니다. 예: `KRW`
`Description`	string	Optional	상품 설명입니다.
`DisplayOriginalPrice`	string	Optional	화면 표시용 할인 전 가격입니다. 예: `₩1,100`
`DisplayPrice`	string	Optional	화면 표시용 가격입니다. 예: `1,200 KRW`
`OriginalPrice`	decimal	Optional	할인 전 가격입니다. 통화에 따라 소수점이 포함될 수 있습니다. 예: `1100` 또는 `11.00`
`Price`	decimal	Optional	가격입니다. 통화에 따라 소수점이 포함될 수 있습니다. 예: `1200` 또는 `9.99`
`ProductId`	string	Optional	상품의 고유 식별자(PID)입니다.
`ProductType`	string	Optional	상품 유형입니다. `subscription`(구독), `consumable`(소모성)
`Title`	string	Optional	상품 제목입니다. 예: `1000 Gold`

응답 예시

Unity

// Success 분기에서 success.Data 예시
// success.Data.ProviderId = ProductProviderId.Steam
// success.Data.Currency = "KRW"
// success.Data.Products[0].ProductId = "com.game.product1"
// success.Data.Products[0].Title = "1000 Gold"
// success.Data.Products[0].Price = 1200.0
// success.Data.Products[0].DisplayPrice = "1,200 KRW"
// success.Data.Products[0].ProductType = "consumable"

응답 상태

아래 표에는 PaymentsFetchSteamProductsResult의 성공 결과와 이 메서드에서 정의한 도메인별 결과(Outcome)를 정리했습니다. 요청 수행이 불가능한 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

응답 케이스	설명	앱 클라이언트 대응
`Success`	상품 목록 조회에 성공했습니다. `Data`에 표준 형식 상품 목록이 담깁니다.	상품 목록으로 상점 화면 구성
`PaymentBadRequest`	요청을 처리할 수 없습니다.	요청 값과 호출 조건을 점검
`PaymentInvalidParameter`	유효하지 않은 파라미터입니다.	요청 필드 값을 점검 후 재요청
`UnknownOutcome`	SDK가 알 수 없는 도메인별 결과입니다.	실패로 처리하고 결과 코드를 기록
`Failure`	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

다음 단계

상품을 구매합니다.