> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Marketplace 통합 - Microsoft Store
> Partner Center 애드온을 설정하고 XBOX 및 Windows 인앱 구매 리뎀션을 위해 Microsoft Store 제품을 PlayFab Economy v2 번들에 연결합니다.
# Marketplace 통합: Microsoft Store
이 자습서에서는 [RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items) API를 사용하여 PlayFab Economy v2를 통해 Microsoft Store 인앱 구매(XBOX 포함)를 리뎀션하는 방법을 보여줍니다.
이 자습서를 마치면 다음을 완료합니다.
* Partner Center에서 애드온 생성
* 필수 Partner Center 및 PlayFab 설정 구성
* Microsoft Store 제품을 PlayFab 카탈로그 번들에 연결
* Redeem API 호출 및 플레이어의 인벤토리에서 아이템 확인
## 필수 구성 요소
1. 앱에 액세스할 수 있는 [Partner Center](https://partner.microsoft.com/) 계정.
2. Partner Center에 이미 만들어진 앱.
3. [Game Manager](https://developer.playfab.com/)에 이미 만들어진 타이틀.
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](https://partner.microsoft.com/)에 로그인하여 앱으로 이동합니다.
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에서 올바르게 작동합니다. 이 제품 유형으로 안전하게 진행할 수 있습니다.
5. 애드온을 만든 후 Partner Center에 표시된 **Store ID**—영숫자 문자열(예: `9NBLGGH42CFD`)을 기록해 두세요. PlayFab에 이 값을 사용하고, 개발자 정의 Product ID나 애드온 이름은 **사용하지 마세요**.
제품 유형에 대한 자세한 내용은 [Choosing the right product type](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/getting-started/xstore-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](https://partner.microsoft.com/)에서 **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)](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-authenticating-your-service#additional-configuration-required-to-view-and-manage-products-with-delegated-authentication-xsts-tokens)를 참조하세요.
## 3단계: Game Manager에서 XBOX Network 애드온 활성화
XBOX Network 애드온은 Partner Center 제품을 PlayFab 타이틀에 연결하고 Microsoft Store 리뎀션을 위한 XBOX 토큰 검증을 활성화합니다.
1. [Game Manager](https://developer.playfab.com/)를 열고 **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](/services/playfab/identity/player-identity/platform-specific-authentication/xbox-live-add-on)을 참조하세요.
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](https://developer.playfab.com/)에서 **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](/services/playfab/economy-monetization/economy-v2/catalog/content-types-tags-and-properties#alternate-ids)를 참조하세요.
## 5단계: XBOX 토큰 획득 및 제공
[RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items) API를 호출할 때 `XboxToken` 매개 변수에 유효한 XBOX 토큰을 제공해야 합니다.
* **GDK C API**를 사용하는 경우 다음을 사용합니다.
```cpp theme={null}
XUserGetTokenAndSignatureAsync // with method "POST", URL "https://playfabapi.com/", and empty body ""
```
세 매개 변수(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](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-managing-consumables-and-refunds)를 참조하세요.
## 문제 해결
`RedeemMicrosoftStoreInventoryItems` 호출이 성공적으로 반환(HTTP 200)되지만 응답의 `Succeeded`, `Failed`, `TransactionIds` 배열이 모두 비어 있으면 Microsoft Store Collections API가 리뎀션할 일치하는 아이템을 찾지 못한 것입니다. 이 동작은 일반적으로 구성 문제 때문입니다. 다음 항목을 확인하세요.
| 문제 | 해결 방법 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **잘못된 제품 유형** | 애드온이 Store-managed consumable이 아닌 **Developer-managed consumable** 또는 **Durable**인지 확인하세요. PlayFab은 Store-managed consumables를 지원하지 않습니다. |
| **PlayFab의 잘못된 Store ID** | Marketplace Mapping 값이 개발자 정의 Product ID나 애드온 이름이 아닌 **Store ID**(`9NBLGGH42CFD`와 같은 영숫자 문자열)와 일치하는지 확인하세요. |
| **번들이 게시되지 않음** | PlayFab 카탈로그에서 번들을 게시하세요. 드래프트 번들은 리뎀션 중 일치하지 않습니다. |
| **Product Group 구성 누락** | 게임과 애드온이 올바른 Dev Studio 및 Business Partner ID에 연결된 Product Group에 포함되어 있는지 확인하세요. Product Group 구성은 가장 흔히 놓치는 단계입니다. [2단계](#step-2-configure-product-group-dev-studio-and-business-partner-id)를 참조하세요. |
| **XBOX Network 애드온이 구성되지 않음** | Game Manager에서 XBOX Network 애드온을 설치하고 구성하세요. [3단계](#step-3-enable-the-xbox-network-add-on-in-game-manager)를 참조하세요. |
| **리뎀션되지 않은 구매 없음** | API가 감지하고 리뎀션할 수 있으려면 플레이어가 제품의 리뎀션되지 않은 구매를 가지고 있어야 합니다. 먼저 테스트 구매를 하세요. |
| **소모품이 이행되지 않음** | PlayFab은 리뎀션 후 Developer-managed consumables를 자동으로 이행합니다. 소모품이 한 번 리뎀션되었지만 다시 리뎀션되지 않는 경우 `RedeemMicrosoftStoreInventoryItems` 호출을 다시 시도하세요. 문제가 지속되면 지원 채널을 통해 PlayFab 팀에 에스컬레이션하세요. [Managing consumables and refunds](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-managing-consumables-and-refunds)를 참조하세요. |
| **Sandbox 불일치** | 애드온이 테스트 중인 것과 동일한 sandbox에 게시되었는지 확인하세요. XBOX 토큰은 sandbox 컨텍스트를 전달하므로 둘 다 일치해야 합니다. |
| **잘못된 XBOX 토큰** | 토큰이 올바른 매개 변수(메서드 `POST`, URL `https://playfabapi.com/`, 빈 본문 문자열 `""`)로 얻어졌는지 확인하세요. |
| **플레이어가 XBOX ID로 인증되지 않음** | 플레이어는 XBOX Live ID(예: `LoginWithXbox`를 통해)를 사용하여 PlayFab에 로그인해야 합니다. 다른 ID 유형은 리뎀션에 필요한 XBOX 컨텍스트가 없습니다. |
API가 HTTP 오류(예: 400)를 반환하는 경우 다음 코드에 대한 오류 응답을 확인하세요.
| 오류 코드 | 설명 |
| --------------------------------- | -------------------------------------------------------- |
| `InvalidCatalogItemConfiguration` | PlayFab 카탈로그에서 번들 또는 Marketplace Mapping이 잘못 구성되었습니다. |
| `InvalidXboxLiveToken` | XBOX 토큰이 잘못되었거나, 만료되었거나, 잘못된 매개 변수로 얻어졌습니다. |
| `AccountNotLinked` | 플레이어의 PlayFab 계정이 XBOX Live ID에 연결되어 있지 않습니다. |
| `XboxInaccessible` | PlayFab이 XBOX 서비스에 연결할 수 없습니다. 오류는 일시적일 수 있습니다. |
| `XboxXASSExchangeFailure` | XSTS 토큰 교환이 실패했습니다. Business Partner 및 신뢰 당사자 구성을 확인하세요. |
호출이 성공(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](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-requesting-a-userstoreid)과 [Authenticating your service — User Store IDs](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-authenticating-your-service#authenticating-through-microsoft-entra-id-and-user-store-ids)를 참조하세요.
## 참고 항목
* [RedeemMicrosoftStoreInventoryItems API reference](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items)
* [Fraud prevention 빠른 시작](/services/playfab/economy-monetization/economy-v2/fraud-prevention/quickstart)
* [XBOX Live add-on configuration](/services/playfab/identity/player-identity/platform-specific-authentication/xbox-live-add-on)
* [Authenticating your service (XSTS tokens)](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-authenticating-your-service)
* [Choosing the right product type](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/getting-started/xstore-choosing-the-right-product-type)
* [Consumable-based ecosystems](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/fundamentals/xstore-consumable-based-ecosystems)
* [Managing consumables and refunds](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-managing-consumables-and-refunds)
* [Alternate IDs (Marketplace Mapping)](/services/playfab/economy-monetization/economy-v2/catalog/content-types-tags-and-properties#alternate-ids)
* [Apple 앱을 Game Manager에 성공적으로 통합하는 방법](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/apple)
* [Google 앱을 Game Manager에 성공적으로 통합하는 방법](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/google)
## Related topics
- [Microsoft Store Marketplace 리뎀션](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/microsoft.md)
- [Fraud prevention 빠른 시작](/ko/services/playfab/economy-monetization/economy-v2/fraud-prevention/quickstart.md)
- [Marketplace 통합 - 개요](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/overview.md)
- [Marketplace 통합 - Apple](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/apple.md)
- [Marketplace 통합 - Google](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/google.md)