Skip to main content

​
PlayFab과 Microsoft Store를 설정하여 구매 활성화

이 자습서에서는 다음을 수행하는 방법을 보여줍니다.
  • Microsoft Store에서 구매 가능한 제품 만들기
  • PlayFab 번들에 매핑
  • RedeemMicrosoftStoreInventoryItems API를 사용하여 구매한 아이템을 플레이어의 인벤토리로 리뎀션

​
필수 구성 요소

  1. PlayFab의 Game Manager의 타이틀.
  2. 다음을 포함하는 선택한 타이틀과 Microsoft Store 간의 기존 통합:
    • Game Manager에 설치되고 구성된 XBOX Network 애드온.
    • Partner Center에 구성된 Product Group, Dev Studio, Business Partner ID.
  3. 앱에 액세스할 수 있는 Partner Center 계정.
  4. Partner Center에 이미 만들어진 앱.
  5. Redeem API를 호출하는 플레이어는 XBOX Live ID(예: LoginWithXbox를 통해)를 사용하여 PlayFab에 인증되어야 합니다. 다른 ID 유형(예: CustomID 또는 이메일)으로 인증된 플레이어는 이 플로우에 필요한 XBOX 컨텍스트가 없습니다.

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

마켓플레이스 통합 설정의 일부로 Partner Center에서 애드온을 만들지 않은 경우 다음 단계를 따르세요.
  1. Partner Center에 로그인하여 앱으로 이동합니다.
  2. Add-ons에서 Create a new add-on을 선택합니다.
  3. 적절한 제품 유형을 선택합니다.
    • 재구매 가능한 아이템(통화, 소모품 팩)의 경우 Developer-managed consumable.
    • 일회성 구매(DLC, 시즌 패스, 코스메틱 잠금 해제)의 경우 Durable.
  4. 애드온 구성(가격, 설명 등)을 완료하고 제출합니다.
  5. 애드온을 만든 후 Partner Center에 표시된 Store ID—영숫자 문자열(예: 9NBLGGH42CFD)을 기록해 두세요. PlayFab의 마켓플레이스 매핑에 이 값을 사용하고, 개발자 정의 Product ID나 애드온 이름은 사용하지 마세요.
Store-managed consumables는 지원되지 않습니다. RedeemMicrosoftStoreInventoryItems API에서는 Developer-managed consumables와 Durables만 작동합니다. Partner Center는 Developer-managed consumables가 XBOX에서 지원되지 않는다고 제안하는 경고를 표시할 수 있습니다. 이 경고는 PlayFab 리뎀션 플로우를 사용할 때는 적용되지 않습니다. 자세한 내용은 Choosing the right product type을 참조하세요.
  1. 테스트할 sandbox나 환경에 애드온을 게시합니다.

​
2단계: Game Manager에서 번들 만들기

Game Manager에서 번들을 만들기 전에 카탈로그에서 번들에 추가하려는 아이템을 만들고 게시하세요. 아이템 만드는 방법에 대한 안내가 필요하면 이 단계를 참조하세요.
Game Manager와 Microsoft Store 간에 마켓플레이스 매핑을 활성화하려면 Game Manager에서 번들을 만들어야 합니다. 번들은 다양한 수량의 여러 아이템을 포함할 수 있으며, PlayFab은 리뎀션되면 이를 플레이어의 인벤토리에 추가합니다. 다음 단계를 따르세요.
  1. Game Manager로 이동하여 Title로 이동합니다.
  2. 왼쪽 탐색 메뉴에서 Engage > Economy를 선택합니다.
  3. Bundles 탭을 선택합니다.
  4. New bundle을 선택합니다.
  5. 아이템 및 가격과 같이 번들에 원하는 정보를 추가합니다.
  6. 페이지 끝까지 아래로 스크롤하여 플레이어가 즉시 리뎀션할 수 있도록 하려면 Save and publish를 선택합니다. 나중에 게시하려면 Save as draft를 선택합니다.

​
번들에 아이템 추가

번들 자체는 플레이어에게 아이템을 부여하지 않습니다. 먼저 아이템을 연결해야 합니다. 리뎀션되면 번들은 특정 플레이어에게 해당 아이템을 부여합니다. 번들에 아이템을 추가하려면:
  1. 편집 모드에서 Items 섹션으로 이동합니다.
  2. Add를 선택합니다. 모든 카탈로그 아이템을 표시하는 창이 나타납니다.
  3. 원하는 아이템을 찾아 옆에 있는 Add를 선택합니다.
  4. 하단의 Add 버튼을 선택합니다.

​
3단계: 마켓플레이스 매핑 활성화

플레이어가 Microsoft Store에서 제품을 구매할 때 Game Manager에서 올바르게 일치되고 할당되도록 하려면 번들의 Marketplace Mapping을 구성해야 합니다.
  1. 편집 모드에서 번들로 이동합니다.
  2. Marketplace Mapping 섹션까지 아래로 스크롤합니다.
  3. Marketplace 드롭다운에서 MicrosoftStore(대/소문자 구분, 정확히 MicrosoftStore여야 함)를 선택합니다.
  4. Marketplace ID의 경우 Partner Center의 정확한 Store ID(예: 9NBLGGH42CFD)를 사용합니다. 개발자 정의 Product ID를 사용하지 마세요.
  5. 해당 행 오른쪽에서 + 를 선택하고 변경 사항을 저장합니다.
번들이 리뎀션 중 일치되려면 (드래프트로 남겨두지 않고) 게시되어야 합니다. 리뎀션 API는 게시되지 않은 카탈로그 아이템을 감지하지 않습니다.
alternate ID에 대한 자세한 내용은 Alternate IDs를 참조하세요.

​
4단계: 플레이어 인증

리뎀션 호출을 하기 전에 플레이어가 올바르게 인증되었는지 확인해야 합니다. XBOX 및 Microsoft Store 시나리오의 경우 LoginWithXbox를 사용하여 플레이어를 PlayFab로 인증합니다. LoginWithXbox 호출이 성공하면 PlayFab은 X-EntityToken 키가 있는 리뎀션 호출의 헤더에서 사용해야 하는 EntityToken을 반환합니다.

​
5단계: XBOX 토큰 획득

RedeemMicrosoftStoreInventoryItems API는 XboxToken 매개 변수에 유효한 XBOX 토큰이 필요합니다. 이 토큰은 인증에 사용되는 EntityToken과 별개입니다.
  • GDK C API를 사용하는 경우 다음을 사용합니다.
세 매개 변수(method, URL, body) 모두 표시된 대로 정확히 제공해야 합니다. 잘못 얻은 토큰은 Microsoft Store Collections API 쿼리가 조용히 실패하여 아이템을 반환하지 않습니다.

​
6단계: 구매하기

PlayFab을 통해 리뎀션하기 전에 플레이어는 Microsoft Store에서 애드온을 구매해야 합니다. 이 구매는 XBOX 또는 Windows Store 인터페이스를 통해 이루어질 수 있습니다.
sandbox 환경에서 테스트하는 경우 플레이어 계정과 애드온이 모두 동일한 sandbox에 게시되어 있는지 확인하세요. 리뎀션 API가 리뎀션할 아이템을 찾으려면 플레이어의 계정에 리뎀션되지 않은 구매가 있어야 합니다.

​
7단계: 구매 리뎀션

플레이어가 인증되고 XBOX 토큰이 획득되고 구매가 완료되면 RedeemMicrosoftStoreInventoryItems API를 호출할 준비가 되었습니다. EntityToken을 X-EntityToken 헤더로 포함하고 요청 본문에 XBOX 토큰을 제공하세요.

​
리뎀션 작동 방식

RedeemMicrosoftStoreInventoryItems 호출이 이루어지면 PlayFab은 XBOX 토큰을 사용하여 Microsoft Store Collections API를 쿼리하여 플레이어의 계정과 연결된 리뎀션되지 않은 구매를 찾습니다. 그런 다음 이러한 구매를 PlayFab 번들 Marketplace Mappings에 구성된 Store ID와 일치시키고 해당 아이템을 부여합니다. 성공적인 응답에는 다음을 포함하는 RedeemMicrosoftStoreInventoryItemsResponse와 함께 200 상태 코드가 포함됩니다.
  • Succeeded—성공적으로 리뎀션된 아이템 목록.
  • Failed—리뎀션에 실패한 아이템 목록.
  • TransactionIds—각 리뎀션 트랜잭션에 대한 ID.
각 리뎀션 작업은 플레이어의 트랜잭션 이력에서 해당 이벤트를 트리거하며, Game Manager의 플레이어 개요 페이지 아래의 Transaction History (V2) 탭에서 검색할 수 있습니다. 플레이어의 트랜잭션 이력에 있는 레코드와 함께 items_redeemed PlayStream 이벤트도 트리거되고 기록됩니다. Game Manager의 왼쪽 탐색 모음의 Analyze 섹션 아래에 있는 Data 페이지로 이동하여 타이틀의 이러한 로그에 액세스할 수 있습니다.

​
Developer-managed consumables의 이행

리뎀션된 제품이 Developer-managed consumable인 경우, PlayFab은 성공적인 리뎀션 후 사용자를 대신하여 Microsoft Store에 자동으로 이행됨(소비됨)으로 보고합니다. 이행 단계는 플레이어가 동일한 소모품을 재구매하기 전에 필요합니다. 성공적인 리뎀션 후에도 소모품이 이행된 것으로 표시되지 않는 경우 RedeemMicrosoftStoreInventoryItems 호출을 다시 시도하세요. 문제가 지속되면 지원 채널을 통해 PlayFab 팀에 에스컬레이션하세요. Durables는 일회성 구매이므로 이행이 필요하지 않습니다. 자세한 내용은 Managing consumables and refunds를 참조하세요.

​
문제 해결

리뎀션 호출이 200을 반환하지만 세 배열(Succeeded, Failed, TransactionIds) 모두가 비어 있는 경우 Microsoft Store Collections API가 일치하는 아이템을 찾지 못한 것입니다. 이 결과는 일반적으로 구성 문제를 나타냅니다. 일반적인 원인과 해결 방법의 전체 목록은 Microsoft Store 통합 가이드의 문제 해결 섹션을 참조하세요. API가 HTTP 오류(예: 400)를 반환하는 경우 InvalidCatalogItemConfiguration, InvalidXboxLiveToken 또는 AccountNotLinked와 같은 코드에 대한 오류 응답을 확인하세요.

​
참고 항목

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

관련 항목

Marketplace 리뎀션 - 개요Steam Marketplace 리뎀션Google Marketplace 리뎀션Apple App Store 인앱 구매 리뎀션Marketplace 통합 - Microsoft Store