> ## 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.

# XBOX services 타이틀을 위한 PlayFab 통합

> GDK 타이틀에서 XBOX services 및 PlayFab에 플레이어를 로그인시키고, 연결된 계정을 프로비저닝하며, PlayFab 이코노미를 통해 Microsoft Store 인앱 구매를 연결합니다.

PlayFab은 라이브 게임을 위한 Microsoft의 백엔드 서비스(backend-as-a-service)입니다 — 이코노미, 카탈로그, 리더보드, 클라우드 스크립트, 분석, 매치메이킹 및 PlayFab Party 음성/데이터 네트워킹. XBOX services 위에 깔끔하게 계층화됩니다. XBOX services는 **플레이어에게 노출되는 ID**(게이머태그, 친구, 도전 과제, 상태, MPSD 세션)를 소유하고, PlayFab은 **백엔드 라이브 서비스 데이터**(인벤토리, 통화, 사용자 정의 사용자 데이터, 텔레메트리)를 소유합니다.

**PlayFab Party**, **Microsoft Store 인앱 구매**를 위한 PlayFab 이코노미, PlayFab 리더보드 또는 기타 PlayFab 서비스를 사용하는 모든 GDK 타이틀은 **두 스택 모두**에 플레이어를 로그인시키고 두 ID를 연결된 상태로 유지해야 합니다.

<Info>
  이 페이지는 통합의 XBOX 측면에 중점을 둡니다 — 로그인된 XUser에 연결된 PlayFab 계정을 프로비저닝하는 방법과 Microsoft Store 엔타이틀먼트 흐름이 PlayFab 이코노미에 어떻게 연결되는지를 다룹니다. PlayFab 기능 전반(Game Manager, 카탈로그, 클라우드 스크립트, 매치메이킹, Party)에 대해서는 [PlayFab 설명서](https://learn.microsoft.com/gaming/services/playfab/)를 참조하세요.
</Info>

## XBOX 및 PlayFab 사용자 계정

XBOX services 계정과 PlayFab 계정은 두 개의 별도 ID입니다:

* **XBOX services 계정** — 플레이어에게 노출됨. 플레이어의 Microsoft 계정(MSA)이 소유합니다. 게이머태그, XUID, 친구, 도전 과제, 상태를 포함합니다.
* **PlayFab 계정** — 백엔드에서 사용됨. **PlayFab TitleId**(PlayFab의 [Game Manager](https://developer.playfab.com/)에서 타이틀을 만들 때 할당되는 4–6자리 16진수 문자열) 내의 **Entity ID**로 식별됩니다. XBOX 타이틀 ID와 동일하지 않습니다.

GDK 타이틀에서 PlayFab 기능(Party 음성 채팅, 이코노미, 리더보드)을 사용하려면 로그인한 모든 XUser가 PlayFab 타이틀 컨텍스트에서 프로비저닝된 연결된 PlayFab 계정을 가지고 있어야 합니다. 로그인 흐름이 끝날 때까지:

* 플레이어가 `XUserAddAsync`로 추가되었고 `XUserHandle`을 보유합니다.
* 해당 플레이어에 대한 PlayFab 계정이 PlayFab TitleId 아래에 존재합니다(첫 로그인 시 자동으로 프로비저닝됨).
* XBOX와 PlayFab 계정이 연결되어 있으며, 타이틀은 인증된 PlayFab REST/SDK 호출을 위한 유효한 자격 증명(Entity ID + PlayFab 토큰)을 보유합니다.

<Warning>
  PlayFab **TitleId는 XBOX 타이틀 ID와 동일하지 않습니다**. 게임(또는 샤드)당 하나의 PlayFab 타이틀을 PlayFab Game Manager에서 프로비저닝하고 해당 TitleId를 빌드 구성에 하드 코딩하세요.
</Warning>

## PlayFab에 플레이어 로그인

지원되는 두 가지 로그인 경로가 있습니다. 사용하는 PlayFab 서비스에 따라 하나를 선택하세요:

<CardGroup cols={2}>
  <Card title="PlayFab Services SDK" icon="star" href="#playfab-services-sdk-recommended">
    **모든 타이틀에 권장됨.** GDK에 게이밍 확장 라이브러리(`PlayFab.Services.C`)로 제공됩니다. 이코노미, 리더보드, 클라우드 스크립트, 매치메이킹, 그리고 **Party 이외의 기능**을 사용하는 모든 타이틀에 사용됩니다.
  </Card>

  <Card title="PlayFab Party Xbox Live Helper Library" icon="headset">
    **PlayFab Party가 사용하는 유일한 PlayFab 서비스**이고 XBOX services가 유일한 인증 공급자인 경우에만 사용하세요. GDK 내 PlayFab Party SDK와 함께 제공됩니다.
  </Card>
</CardGroup>

### PlayFab Services SDK (권장)

PlayFab Services SDK는 GDK와 함께 제공되며 `PFAuthenticationLoginWithXUserAsync`를 노출합니다. 이 함수는 `XUserHandle`을 받아 한 번의 호출로 플레이어를 PlayFab에 로그인시킵니다. 첫 실행 시 연결된 PlayFab 계정을 자동으로 프로비저닝하려면 `createAccount = TRUE`로 설정하세요.

**설정**

1. [GDK](https://aka.ms/gdkdl)를 설치합니다.
2. **PlayFab.Services.C** 게이밍 확장 라이브러리를 프로젝트에 추가합니다:
   * Visual Studio에서 프로젝트를 열고 → **프로젝트** → **속성**을 선택합니다.
   * **구성 속성** → **Gaming Desktop** → **일반**에서 **Gaming Extension Libraries**를 열고 **PlayFab.Services.C**를 추가합니다.

**권장 로그인 흐름**

1. [`XUserAddAsync`](/reference/system/xuser/xuser_members)로 플레이어를 XBOX 계정에 로그인시키고 반환된 `XUserHandle`을 보관합니다.
2. `PFAuthenticationLoginWithXUserAsync`를 호출합니다:
   * `XUserHandle`을 `user` 매개변수로 전달합니다.
   * 첫 로그인 시 PlayFab이 연결된 계정을 자동으로 프로비저닝하도록 `createAccount = TRUE`로 설정합니다.
3. 결과로 얻은 PlayFab 자격 증명(Entity ID + PlayFab 토큰)을 세션 동안 유지하고, 이후의 모든 PlayFab 호출에 사용합니다.

전체 안내는 [GDK용 PlayFab Services SDK 빠른 시작](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart)을 참조하세요.

### PlayFab Party XBOX Live Helper Library

PlayFab Party가 타이틀이 사용하는 **유일한** PlayFab 서비스라면 PlayFab Services SDK를 건너뛰고 GDK의 PlayFab Party SDK와 함께 번들로 제공되는 Party XBOX Live Helper Library를 통해 로그인할 수 있습니다.

**흐름**

1. `XUserAddAsync`로 플레이어를 XBOX에 로그인시킵니다.
2. 채팅이 처음 시작될 때 `XUserGetId`로 XUID를 검색합니다.
3. XUID로 `PartyXblManager::CreateLocalChatUser`를 호출하여 \*\*`PartyXblLocalChatUser`\*\*를 생성합니다.
4. 해당 사용자 객체로 `PartyXblManager::LoginToPlayFab`를 호출합니다.
   * GDK(콘솔 및 PC)와 XDK에서는 헬퍼 라이브러리가 내부적으로 필요한 XBOX services 토큰을 가져와 XBOX 자격 증명으로 플레이어를 PlayFab에 로그인시키고, 첫 로그인 시 PlayFab 계정을 자동으로 생성합니다. 이 방법으로 생성된 계정에는 이메일이나 사용자 이름이 첨부되어 있지 않습니다.
   * GDK/XDK가 아닌 타이틀(예: GDK 없는 PC Win32)에서는 대신 `PartyXblTokenAndSignatureRequestedStateChange`를 받습니다. XBOX services 토큰을 직접 가져와 `PartyXblManager::CompleteGetTokenAndSignatureRequest`를 통해 다시 전달합니다.
5. 성공 시 PlayFab Entity ID와 토큰을 담은 `PartyXblLoginToPlayFabCompletedStateChange`를 받습니다.

<Note>
  **원격** 사용자의 경우 `PartyXblManager::CreateRemoteChatUser`를 사용하세요 — 원격 사용자 흐름에는 인증이나 토큰 교환이 필요하지 않습니다.
</Note>

## XUser는 ID 브리지입니다

다운스트림의 모든 것 — PlayFab 로그인, MPSD 세션 쓰기 토큰, S2S 호출, 엔타이틀먼트 쿼리 — 은 `XUserAddAsync`에서 반환된 `XUserHandle`로 시작됩니다. PlayFab 통합에 중요한 두 개의 API가 있습니다:

| API                                                      | 목적                                                                        |
| -------------------------------------------------------- | ------------------------------------------------------------------------- |
| [`XUserAddAsync`](/reference/system/xuser/xuser_members) | 플레이어를 XBOX 계정에 로그인시키고 `XUserHandle`을 가져옵니다.                               |
| `XUserGetTokenAndSignatureUtf16Async`                    | 헬퍼 라이브러리 경로(Win32 폴백) 또는 사용자 정의 S2S 브리지를 위해 XBOX services 토큰 + 서명을 검색합니다. |

더 넓은 로그인 모델(MSA, XSTS 토큰, 샌드박스 범위 지정)에 대해서는 [XBOX services ID](/services/xbox-services/fundamentals/identity/xs-identity-overview)를 참조하세요.

## 크로스 플랫폼 타이틀

PlayFab은 많은 플랫폼 인증 공급자를 지원합니다. iOS, Android, Steam, PlayStation에서 동일한 타이틀을 출시할 때, 모든 플레이어를 XUser를 통해 라우팅하려고 시도하지 **마세요** — 플랫폼의 기본 PlayFab 인증 공급자를 사용하세요:

* **iOS** — Apple ID (`LoginWithApple`).
* **Android** — Google Play Games (`LoginWithGoogleAccount`).
* **Steam** — `LoginWithSteam`.
* **XBOX / GDK PC** — `PFAuthenticationLoginWithXUserAsync` (이 페이지).

각 플랫폼 로그인은 자체 PlayFab 계정을 프로비저닝하고 동일한 PlayFab 타이틀에 연결합니다. 동일한 PlayFab 계정으로 여러 플랫폼을 이동하는 플레이어는 연결된 ID가 PlayFab 내에서 병합됩니다.

전체 매트릭스에 대해서는 [플랫폼별 PlayFab 인증](https://learn.microsoft.com/gaming/services/playfab/features/authentication/platform-specific-authentication/)을 참조하세요.

## PlayFab 이코노미를 통한 Microsoft Store 인앱 구매

Microsoft Store를 통해 인앱 아이템을 판매하는 GDK 타이틀의 경우, PlayFab은 **이코노미 백엔드** 역할을 하고 Microsoft Store가 실제 트랜잭션을 처리합니다. PlayFab은 **엔타이틀먼트 메서드**를 사용하여 Microsoft Store 구매를 플레이어의 PlayFab 인벤토리에 조정합니다 — 플레이어가 먼저 XBOX 계정에 로그인되어 있어야 합니다.

### 흐름

1. 플레이어가 XBOX(`XUserAddAsync`)와 PlayFab(`PFAuthenticationLoginWithXUserAsync`)에 로그인됩니다.
2. 플레이어가 기기에서 Microsoft Store를 통해 아이템을 구매합니다.
3. 타이틀이 구매를 PlayFab에 알립니다.
4. PlayFab이 XBOX 토큰으로 [`ConsumeMicrosoftStoreEntitlements`](https://learn.microsoft.com/rest/api/services/playfab/client/platform-specific-methods/consume-microsoft-store-entitlements)를 호출하여 플레이어의 PlayFab 인벤토리를 동기화하고 새로운 아이템을 부여합니다.

<Warning>
  GDK 타이틀에서는 **Microsoft Store** PlayFab 애드온과 `ConsumeMicrosoftStoreEntitlements`를 사용하세요. 레거시 XBOX 애드온 / `ConsumeXboxEntitlements`는 사용하지 **마세요**(해당 경로는 XDK 타이틀 전용). Universal Windows Platform 애드온은 사용 중단되었습니다.
</Warning>

### Partner Center 사전 요구 사항

* [XBOX Creators Program](https://www.xbox.com/developers/creators-program) 또는 관리 파트너에 등록됨.
* XBOX 비즈니스 파트너 정보와 동일한 게시자 GUID(`aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`)로 Partner Center에 게시자 ID가 구성됨.
* XBOX services를 사용하기 위한 컨셉 승인.

Partner Center에서 **게임 설정 → XBOX services** 아래에서 **전체 XBOX services 기능 세트 사용(컨셉 승인 필요)** 또는 **XBOX Creators Program 사용** 중 하나를 선택한 다음, 타이틀 아래에서 애드온을 만드세요.

<Note>
  PlayFab의 Microsoft Store 애드온은 Partner Center에서 **스토어 관리 소모품**을 지원하지 **않습니다**. **개발자 관리 소모품**(또는 내구재)만 생성하세요.
</Note>

### Partner Center와 PlayFab에서 일치하는 항목 만들기

Partner Center의 **제품 ID**와 PlayFab의 **아이템 ID**는 엔타이틀먼트 동기화가 작동하려면 정확히 일치해야 합니다.

1. Partner Center → **애드온** → **새 소모품(개발자 관리) 만들기**(또는 내구재)를 선택합니다. 고유한 **제품 ID**(예: `MyItem_001`)를 입력합니다.
2. [PlayFab Game Manager](https://developer.playfab.com/) → **Engage** → **Economy** → **New item**을 선택합니다. **Item ID**에 동일한 문자열(`MyItem_001`)을 입력합니다. Partner Center와 일치하도록 Consumable 또는 Durable로 표시하고 저장합니다.

### 용어 참조

| 개념        | PlayFab    | Partner Center / Microsoft Store   |
| --------- | ---------- | ---------------------------------- |
| 고유 식별자    | Item ID    | Product ID                         |
| 소모품       | Consumable | Consumable (Developer-managed)     |
| 내구재       | Durable    | Durable *또는* Durable with packages |
| 가상 인게임 상점 | Store      | *(해당 없음)*                          |

### 카탈로그 및 스토어 — 전역적으로 하나의 Item ID

PlayFab을 사용하면 타이틀당 여러 **카탈로그**를 정의할 수 있으며 각 카탈로그 내에서 아이템을 **스토어**로 그룹화할 수 있습니다. Microsoft Store 엔타이틀먼트 동기화가 작동하려면 **각 Product ID가 PlayFab 타이틀의 모든 카탈로그 버전에서 정확히 하나의 Item ID와 일치해야 합니다.**

<Warning>
  동일한 `Item ID`가 둘 이상의 카탈로그에 나타나면 엔타이틀먼트 소비가 실패합니다. 주어진 PlayFab 타이틀의 모든 카탈로그에서 아이템 ID를 전역적으로 고유하게 유지하세요.
</Warning>

**잘못됨 — 카탈로그 간에 동일한 ID 재사용:**

| Catalog version | Item ID     | Type       |
| --------------- | ----------- | ---------- |
| MyCatalog\_001  | MyItem\_001 | Consumable |
| MyCatalog\_002  | MyItem\_001 | Consumable |
| MyCatalog\_003  | MyItem\_001 | Durable    |

**올바름 — SKU당 하나의 Item ID, 스토어 간에 자유롭게 재사용:**

| Catalog version | Item ID     | Type       |
| --------------- | ----------- | ---------- |
| MyCatalog\_001  | MyItem\_001 | Consumable |
| MyCatalog\_001  | MyItem\_002 | Durable    |
| MyCatalog\_002  | MyItem\_003 | Consumable |
| MyCatalog\_003  | MyItem\_004 | Durable    |

카탈로그 내의 스토어는 그런 다음 이러한 고유한 아이템의 임의의 하위 집합을 자유롭게 번들할 수 있습니다:

| Store ID     | Item IDs                              |
| ------------ | ------------------------------------- |
| MyStore\_001 | MyItem\_001, MyItem\_002              |
| MyStore\_002 | MyItem\_001                           |
| MyStore\_003 | MyItem\_002, MyItem\_003, MyItem\_004 |

## 참고 항목

* [XBOX services ID](/services/xbox-services/fundamentals/identity/xs-identity-overview) — XUser, MSA, XSTS 토큰, 샌드박스 범위 지정.
* [XBOX 멀티플레이어](/services/xbox-services/multiplayer/index) — 멀티플레이어 전송 옵션으로서의 PlayFab Party.
* [Game Chat 2](/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro) — PlayFab Party 위에 계층화된 Game Chat 2.
* [Multiplayer Activity](/services/xbox-services/multiplayer/mpa/live-mpa-overview) — MPA + PlayFab Party 통합.
* [GDK용 PlayFab Services SDK 빠른 시작](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart)
* [PlayFab 가격](https://playfab.com/pricing/)


## Related topics

- [Identity](/xbox-services/identity.md)
- [Multiplayer](/xbox-services/multiplayer.md)
- [Game Chat](/xbox-services/game-chat.md)
- [Multiplayer Activity](/xbox-services/multiplayer-activity.md)