Skip to main content

​
Marketplace 통합: Microsoft Store

이 자습서에서는 RedeemMicrosoftStoreInventoryItems API를 사용하여 PlayFab Economy v2를 통해 Microsoft Store 인앱 구매(XBOX 포함)를 리뎀션하는 방법을 보여줍니다. 이 자습서를 마치면 다음을 완료합니다.
  • Partner Center에서 애드온 생성
  • 필수 Partner Center 및 PlayFab 설정 구성
  • Microsoft Store 제품을 PlayFab 카탈로그 번들에 연결
  • Redeem API 호출 및 플레이어의 인벤토리에서 아이템 확인

​
필수 구성 요소

  1. 앱에 액세스할 수 있는 Partner Center 계정.
  2. Partner Center에 이미 만들어진 앱.
  3. Game Manager에 이미 만들어진 타이틀.
  4. Redeem API를 호출하는 플레이어는 XBOX Live ID(예: LoginWithXbox를 통해)를 사용하여 PlayFab에 인증되어야 합니다. 다른 ID 유형(예: CustomID 또는 이메일)으로 인증된 플레이어는 이 플로우에 필요한 XBOX 컨텍스트가 없습니다.

​
지원되는 제품 유형

RedeemMicrosoftStoreInventoryItems API는 다음 Microsoft Store 제품 유형을 지원합니다.
  • Developer-managed consumable — 구매하고 사용한 후 다시 구매할 수 있는 제품(예: 게임 내 통화 팩). 게임 서비스는 이행을 추적할 책임이 있습니다.
  • Durable — 한 번 구매하고 영구적으로 소유하는 제품(예: DLC, 확장 팩, 시즌 패스 또는 코스메틱 아이템).
Store-managed consumables는 지원되지 않습니다. PlayFab Economy v2는 Store-managed consumables를 리뎀션할 수 없습니다. 애드온이 Store-managed consumable로 구성되어 있는 경우 Redeem API는 오류 없이 빈 결과와 함께 HTTP 200 응답을 반환하여 문제 진단이 어렵습니다.

​
1단계: Partner Center에서 애드온 만들기

  1. Partner Center에 로그인하여 앱으로 이동합니다.
  2. Add-ons에서 Create a new add-on을 선택합니다.
  3. 적절한 제품 유형을 선택합니다.
    • 재구매 가능한 아이템(통화, 소모품 팩)의 경우 Developer-managed consumable.
    • 일회성 구매(DLC, 시즌 패스, 코스메틱 잠금 해제)의 경우 Durable.
  4. 애드온 구성(가격, 설명 등)을 완료하고 제출합니다.
Developer-managed consumable을 만들 때 Partner Center에 다음과 같은 경고가 표시됩니다: “XBOX requires consumables to be managed, so do not use this option and create a ‘managed consumable’ add-on instead. If you have any questions, contact your Microsoft representative.”* 이 경고는 일반적인 XBOX 플랫폼 지침을 반영하며 PlayFab 리뎀션 플로우에는 적용되지 않습니다. Developer-managed consumables는 PlayFab의 RedeemMicrosoftStoreInventoryItems API와 함께 사용할 때 XBOX에서 올바르게 작동합니다. 이 제품 유형으로 안전하게 진행할 수 있습니다.
  1. 애드온을 만든 후 Partner Center에 표시된 Store ID—영숫자 문자열(예: 9NBLGGH42CFD)을 기록해 두세요. PlayFab에 이 값을 사용하고, 개발자 정의 Product ID나 애드온 이름은 사용하지 마세요.
제품 유형에 대한 자세한 내용은 Choosing the right product type을 참조하세요.

​
2단계: Product Group, Dev Studio 및 Business Partner ID 구성

이 단계에서는 플레이어를 대신하여 Microsoft Store Collections API를 쿼리하기 위해 PlayFab이 사용하는 위임된 XBOX Security Token Service(XSTS) 토큰 플로우를 구성합니다.
Product Group, Dev Studio 및 Business Partner ID 구성은 가장 흔히 놓치는 단계입니다. 이 없이는 Redeem API 호출은 성공(HTTP 200)하지만 Collections API가 아이템을 0개 반환합니다—오류 메시지 없이 빈 Succeeded, Failed, TransactionIds 배열이 결과입니다.
  1. Partner Center에서 Developer Settings > XBOX Live > Web Services로 이동하여 아직 생성하지 않은 경우 Business Partner Certificate를 생성합니다.
  2. Developer Settings > XBOX Live > Business Partner로 이동하여 신뢰 당사자가 연결된 웹 서비스와 일치하는 Business Partner ID를 기록해 두세요.
  3. Dev Studio를 만들거나(또는 기존 것을 사용) Dev Studio ID를 2단계의 Business Partner ID와 일치하도록 설정합니다. Dev Studio에 이미 다른 ID가 있는 경우 기존 값을 변경하는 대신 새 Dev Studio를 만드세요. 변경하면 기존 서비스가 손상될 수 있습니다.
  4. Product Group을 만들고 3단계의 Dev Studio에 할당합니다.
  5. 게임 제품과 모든 애드온을 Included in this product group 목록에 추가합니다. 아이템은 “available” 쪽에서 “included” 쪽으로 명시적으로 이동해야 합니다.
  6. Save를 선택합니다.
  7. 게임의 XBOX Settings 페이지로 이동하여 연결된 Business Partner가 2단계의 것과 일치하는지 확인합니다.
  8. 대상 sandbox 또는 RETAIL 환경에서 게임 제품과 모든 애드온을 Microsoft Store에 다시 게시합니다.
전체 구성 안내는 Configure products with delegated authentication (XSTS tokens)를 참조하세요.

​
3단계: Game Manager에서 XBOX Network 애드온 활성화

XBOX Network 애드온은 Partner Center 제품을 PlayFab 타이틀에 연결하고 Microsoft Store 리뎀션을 위한 XBOX 토큰 검증을 활성화합니다.
  1. Game Manager를 열고 Title을 선택합니다.
  2. 왼쪽 탐색 메뉴에서 Add-ons를 선택합니다.
  3. XBOX Network 애드온(Distribute for XBOX라고 표시됨)을 찾아 선택합니다.
  4. 드롭다운에서 올바른 Seller ID를 선택합니다. 올바른 Seller ID가 표시되지 않는 경우 Sign in with a different partner center account를 선택합니다.
  5. 드롭다운에서 Partner Center Product ID를 선택하고 XBOX Live Title ID(십진수)가 XBOX services > XBOX Settings 아래 Partner Center에 표시된 것과 일치하는지 확인합니다.
  6. 구성을 저장하려면 Install XBOX Network를 선택합니다.
자세한 내용은 XBOX Live add-on configuration을 참조하세요.
Game Manager에는 별도의 Microsoft Store 애드온 페이지(Add-ons 아래에 있음)도 있습니다. 구성이 필요하지 않지만 지원되는 제품 유형 확인과 Dev Studio ID 및 Business Partner ID 설정에 대한 세부 정보를 포함하여 유용한 안내가 포함되어 있습니다.

​
4단계: Marketplace Mapping이 있는 PlayFab 번들 만들기

Microsoft Store 제품을 PlayFab 카탈로그에 연결하려면 Marketplace Mapping(AlternateId)이 있는 Bundle을 만드세요.
  1. Game Manager에서 Economy > Catalog (V2) > Bundles로 이동합니다.
  2. New bundle을 선택합니다(또는 기존 것을 편집).
  3. Marketplace Mapping 섹션에서 새 매핑을 추가합니다.
    • Marketplace type을 MicrosoftStore(대/소문자 구분, 정확히 MicrosoftStore여야 함)로 설정합니다.
    • value를 Partner Center의 정확한 Store ID(예: 9NBLGGH42CFD)로 설정합니다. 개발자 정의 Product ID나 애드온 이름을 사용하지 마세요.
  4. 이 번들이 리뎀션될 때 플레이어가 받을 아이템을 추가합니다(예: 게임 내 통화, 가상 아이템).
  5. 번들을 게시합니다. 게시되지 않은(드래프트) 번들은 리뎀션 중 일치하지 않습니다.
alternate ID에 대한 자세한 내용은 Alternate IDs를 참조하세요.

​
5단계: XBOX 토큰 획득 및 제공

RedeemMicrosoftStoreInventoryItems API를 호출할 때 XboxToken 매개 변수에 유효한 XBOX 토큰을 제공해야 합니다.
  • GDK C API를 사용하는 경우 다음을 사용합니다.
세 매개 변수(method, URL, body) 모두 표시된 대로 정확히 제공해야 합니다. 잘못 얻은 토큰은 Collections API 쿼리가 조용히 실패하여 오류 없이 빈 결과를 반환합니다.

​
6단계: 통합 테스트

통합이 완료된 것으로 간주하기 전에 전체 엔드투엔드 플로우를 확인하세요.
  1. 애드온이 테스트 중인 sandbox 또는 환경에 게시되었는지 확인합니다.
  2. XBOX Live ID를 사용하여 테스트 플레이어로 로그인하고 Microsoft Store를 통해 애드온의 테스트 구매를 합니다. Redeem API가 감지할 것이 있으려면 플레이어의 계정에 리뎀션되지 않은 구매가 있어야 합니다.
  3. 플레이어의 XboxToken을 사용하여 RedeemMicrosoftStoreInventoryItems를 호출합니다.
  4. 응답에 Succeeded 배열의 항목이 포함되어 있고 해당 아이템이 플레이어의 PlayFab 인벤토리에 표시되는지 확인합니다.
Developer-managed consumable 이행: Developer-managed consumable이 리뎀션된 후 PlayFab은 자동으로 사용자를 대신하여 Microsoft Store에 이행됨(소비됨)으로 보고합니다. 이행 단계는 플레이어가 소모품을 다시 구매하기 전에 필요합니다. 성공적인 리뎀션 후에도 소모품이 이행된 것으로 표시되지 않는 경우 RedeemMicrosoftStoreInventoryItems 호출을 다시 시도합니다. 문제가 지속되면 지원 채널을 통해 PlayFab 팀에 에스컬레이션하세요. 자세한 내용은 Managing consumables and refunds를 참조하세요.

​
문제 해결

RedeemMicrosoftStoreInventoryItems 호출이 성공적으로 반환(HTTP 200)되지만 응답의 Succeeded, Failed, TransactionIds 배열이 모두 비어 있으면 Microsoft Store Collections API가 리뎀션할 일치하는 아이템을 찾지 못한 것입니다. 이 동작은 일반적으로 구성 문제 때문입니다. 다음 항목을 확인하세요. API가 HTTP 오류(예: 400)를 반환하는 경우 다음 코드에 대한 오류 응답을 확인하세요.
호출이 성공(HTTP 200)하지만 빈 결과를 반환하고 다른 모든 구성이 올바른 것으로 보이면 먼저 Product Group 구성을 확인하세요. Product Group 단계는 가장 흔히 놓치는 단계입니다.

​
PC / Windows 타이틀에 대한 참고 사항

이 자습서에서는 위임된 XSTS 토큰(XboxToken 매개 변수를 통해 전달)을 사용하는 XBOX 플로우를 다룹니다. PC / Windows 타이틀의 경우 Microsoft는 대신 서비스 간 인증을 위해 Microsoft Entra ID와 함께 User Store ID를 사용할 것을 권장합니다. 자세한 내용은 Requesting a User Store ID for service-to-service authentication과 Authenticating your service — User Store IDs를 참조하세요.

​
참고 항목

마지막 수정일 2026년 8월 24일

관련 항목

Microsoft Store Marketplace 리뎀션Fraud prevention 빠른 시작Marketplace 통합 - 개요Marketplace 통합 - AppleMarketplace 통합 - Google