Skip to main content
인게임 스토어는 일반적으로 세 가지 기본 작업을 포함합니다.
  1. 사용자가 구매할 수 있는 항목 결정
  2. 사용자가 소유하거나 사용 권한이 있는 제품 평가
  3. 적격 제품 구매
이 문서에서는 모범 사례를 반영하여 지속적으로 업데이트되는 InGameStore 샘플에서 파생된 각 작업에 대한 샘플 코드를 보여줍니다.

XStore API 호출 준비

모든 XStore API는 XStoreCreateContext를 사용하여 만든 XStoreContextHandle을 통해 동작합니다. 이 컨텍스트를 사용하면 콘솔에서는 지정된 사용자의 컨텍스트에서, PC에서는 사용 가능한 기본 사용자의 컨텍스트에서 스토어 작업을 수행할 수 있습니다. 콘솔에서는 Suspend 또는 Quick Resume 이벤트가 컨텍스트를 무효화합니다. 이러한 조건을 안전하게 처리하려면 게임이 일시 중단 상태에서 다시 시작될 때마다 XStoreContextHandle을 닫고 다시 만드세요.

1. 사용자가 구매할 수 있는 항목 결정

게임이 일반적으로 판매용으로 제공하는 것은 추가 기능(add-on)입니다. 다음 코드는 어떤 제품이 사용 가능한지 게임에서 알기 위해 필요한 기본 XStoreQueryAssociatedProductsAsync API 호출을 보여줍니다. 이 쿼리는 자동으로 게임과 연결된 구매 가능한 추가 기능만 반환합니다. 게임이 Partner Center의 Product relationship setup 섹션에서 이 제품과 “can sell” 관계로 설정되어 있는 한, 동일한 게시자(즉, 동일한 Partner Center 계정으로 구성됨)와 연결된 관련이 없는 제품도 이 호출에서 반환되도록 만들 수 있습니다. 제품 관계 구성에 대해 자세히 알아보려면 게임의 제품 관계 구성을 참고하세요.

주의 사항

  • XStoreQueryAssociatedProductsAsync로는 구매 가능한 제품만 반환됩니다. 번들에서만 부여되거나 그 외 독립적으로 구매할 수 없도록 설정된 제품은 반환되지 않습니다. 후자의 경우 XStoreQueryProductsAsync를 사용하세요.
  • 반환되는 제품의 수를 사전에 알 수 없으므로 개수를 누적해야 합니다.

페이징

연결된 제품 또는 사용 권한을 쿼리할 때 페이징 처리는 선택 사항이 아닙니다. 서비스에서 반환하는 페이지 수와 페이지당 반환되는 항목 수는 환경 및 서비스 부하에 따라 다를 수 있습니다. 페이징 처리 방법의 예는 XStoreQueryAssociatedProductsAsync를 참고하세요.

기타 옵션

storeId를 알고 있거나 다른 actionFilters가 필요한 경우 XStoreQueryProductsAsync를 사용하여 특정 제품을 쿼리할 수 있습니다. “Action”은 제품에 적용되는 사용 시나리오로, Purchase, License, Gift, Redeem 같은 동사를 포함합니다. XStoreQueryAssociatedProductsForStoreIdAsync를 사용하여 다른 게임의 연결된 제품을 쿼리할 수 있으며, 이는 다른 타이틀의 추가 기능을 교차 판매하는 데 유용할 수 있습니다. XStoreQueryProductForCurrentGameAsync는 현재 실행 중인 게임의 제품만 쿼리하는 API입니다. XStoreShowAssociatedProductsUIAsync는 사용자를 Microsoft Store 앱의 연결된 제품 보기(제품 종류로 필터링됨)로 이동시킵니다. 이 API는 인게임 인터페이스에서 사용 가능한 제품을 나열하는 대신 사용할 수 있는 대안입니다.

2. 사용자가 소유하거나 사용 권한이 있는 제품 평가

이 단계는 앞에서 보인 것과 대부분 동일한 코드를 사용하지만, 다음과 같이 대체합니다. QueryEntitledProducts API는 사용자에게 부여된 제품을 반환합니다. 부여됨(Entitled)이란 사용자가 제품을 직접 소유하거나, 다른 제품(예: 번들 및 구독)을 통해 사용 권한을 충족하거나, 다른 사용자의 공유 사용 권한을 통해 사용 권한을 얻는 것을 의미합니다. 또한 XStoreQueryAssociatedProductsAsync(및 관련 함수)의 결과가 사용 권한을 결정합니다. XStoreProduct 구조체에는 사용자에게 사용 권한이 부여된 경우 true로 설정되는 isInUserCollection 필드가 포함되어 있습니다.

소모품 소유

소모품 수량은 XStoreProduct.skus[i].collectionData.quantity에 표시됩니다. 일반적으로 소모품 제품에는 SKU가 하나뿐입니다. 수량을 조회하는 데 XStoreQueryConsumableBalanceRemainingAsync를 사용할 수도 있지만, 각 호출마다 서비스 호출이 발생하므로 많은 수의 소모품에 대해 개별적으로 사용하지 마세요. 소모품 기반 생태계의 무결성을 유지하려면 서비스 측 유효성 검사와 소모품 사용을 활용하세요. 자세한 내용은 소모품 기반 생태계를 참고하세요.

내구성(Durable) 소유

계정이 제품을 소유하는지 확인하는 것만으로는 게임에서 사용할 수 있는 사용 권한이 있는지 판단하기에 충분하지 않습니다. Durable 제품은 게임의 제품 공유 모델에 설명된 콘텐츠 공유 정책을 준수해야 합니다. 패키지가 있는 durable의 경우 콘텐츠 공유 규칙에 따라 라이선스가 부여될 수 있는지 확인하려면 XStoreAcquireLicenseForPackageAsync를 사용하세요. 패키지가 없는 durable의 경우 동일한 작업을 수행하려면 XStoreAcquireLicenseForDurablesAsync를 사용하세요. 디지털로 라이선스된 게임의 경우 라이선스 부여 가능한 패키지 없는 durable 제품 목록을 반환하려면 XStoreQueryAddOnLicensesAsync를 사용하세요. 자세한 내용은 다운로드 가능한 콘텐츠 관리 및 라이선스 부여패키지 없는 durable 사용 방법을 참고하세요.

3. 적격 제품 구매

구매 가능한 제품의 구매 흐름을 표시하려면 storeIdXStoreShowPurchaseUIAsync API에 전달합니다.
플레이어는 Xbox.com, PC, 모바일 앱 또는 기타 채널에서 Microsoft Store로 명시적으로 전환하여 게임 외부에서도 구매할 수 있습니다. 따라서 요청 시 안정적으로 제품 소유권을 새로 고치는 지점을 게임에 제공하세요. 초기 로그인 흐름은 완벽한 지점이지만, 인게임 스토어로의 전환 과정이나 설정 어딘가에도 새로 고침을 추가하세요.

참조 API 문서

참고

커머스 개요 XStore 개발 및 테스트 활성화 XStore API 참조
마지막 수정일 2026년 8월 31일