> ## Documentation Index > Fetch the complete documentation index at: https://docs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Integração do PlayFab para títulos dos serviços XBOX > Conecte os jogadores aos serviços XBOX e ao PlayFab, provisione contas vinculadas e configure compras no aplicativo da Microsoft Store por meio da economia do PlayFab para títulos GDK. O PlayFab é o back-end como serviço da Microsoft para jogos ao vivo: economia, catálogos, leaderboards, cloud script, análise, matchmaking e rede de voz/dados do PlayFab Party. Ele se integra de forma limpa sobre os serviços XBOX. Os serviços XBOX são responsáveis pela **identidade voltada ao jogador** (gamertag, amigos, conquistas, presença, sessões MPSD), e o PlayFab é responsável pelos **dados do serviço ao vivo de back-end** (inventário, moeda, dados de usuário personalizados, telemetria). Qualquer título GDK que use o **PlayFab Party**, a economia do PlayFab para **compras no aplicativo da Microsoft Store**, os leaderboards do PlayFab ou qualquer outro serviço do PlayFab deve conectar o jogador às **duas** pilhas e manter as duas identidades vinculadas. > [!NOTE] > > Esta página se concentra no lado XBOX da integração: como provisionar uma conta do PlayFab vinculada ao XUser conectado e como o fluxo de direitos da Microsoft Store se conecta à economia do PlayFab. Para conhecer todos os recursos do PlayFab (Game Manager, catálogos, cloud script, matchmaking, Party), veja a [documentação do PlayFab](https://learn.microsoft.com/gaming/services/playfab/). ## Contas de usuário do XBOX e do PlayFab Uma conta dos serviços XBOX e uma conta do PlayFab são duas identidades separadas: * **Conta dos serviços XBOX**: voltada ao jogador. Pertence à conta Microsoft (MSA) do jogador. Contém gamertag, XUID, amigos, conquistas e presença. * **Conta do PlayFab**: nos bastidores. Identificada por uma **Entity ID** dentro do seu **PlayFab TitleId** (uma string de 4 a 6 dígitos hexadecimais atribuída quando você cria um título no [PlayFab Game Manager](https://developer.playfab.com/)). Não é a mesma coisa que a ID do título XBOX. Para usar qualquer recurso do PlayFab (chat de voz do Party, economia, leaderboards) no seu título GDK, cada XUser conectado deve ter uma conta do PlayFab vinculada provisionada no contexto do seu título do PlayFab. Ao final do fluxo de entrada: * O jogador foi adicionado com `XUserAddAsync` e possui um `XUserHandle`. * Existe uma conta do PlayFab para esse jogador no seu PlayFab TitleId (provisionada automaticamente na primeira entrada). * As contas do XBOX e do PlayFab estão vinculadas, e o título possui credenciais válidas (Entity ID + token do PlayFab) para chamadas autenticadas de REST/SDK do PlayFab. > [!WARNING] > > Seu **TitleId do PlayFab não é igual à ID do título XBOX**. Provisione um título do PlayFab por jogo (ou por fragmento) no PlayFab Game Manager e codifique esse TitleId na configuração do seu build. ## Conectar jogadores ao PlayFab Há dois caminhos de entrada com suporte. Escolha um com base nos serviços do PlayFab que você usa: > [card] [PlayFab Services SDK](#playfab-services-sdk-recommended) > > **Recomendado para todos os títulos.** É fornecido como uma Gaming Extension Library (`PlayFab.Services.C`) no GDK. Use para economia, leaderboards, cloud script, matchmaking e qualquer título que use **mais do que apenas o Party**. > [card] PlayFab Party Xbox Live Helper Library > > Use somente se o **PlayFab Party for o único serviço do PlayFab** que você usa e os serviços XBOX forem seu único provedor de autenticação. É fornecida com o SDK do PlayFab Party dentro do GDK. ### PlayFab Services SDK (recomendado) O PlayFab Services SDK é fornecido com o GDK e expõe `PFAuthenticationLoginWithXUserAsync`, que recebe um `XUserHandle` e conecta o jogador ao PlayFab em uma única chamada. Defina `createAccount = TRUE` para provisionar automaticamente a conta do PlayFab vinculada na primeira execução. **Configuração** 1. Instale o [GDK](https://aka.ms/gdkdl). 2. Adicione a Gaming Extension Library **PlayFab.Services.C** ao seu projeto: * Abra o projeto no Visual Studio → **Project** → **Properties**. * Em **Configuration Properties** → **Gaming Desktop** → **General**, abra **Gaming Extension Libraries** e adicione **PlayFab.Services.C**. **Fluxo de entrada recomendado** 1. Conecte o jogador à conta XBOX com [`XUserAddAsync`](https://docs.xbox.com/pt-BR/reference/system/xuser/xuser_members) e guarde o `XUserHandle` retornado. 2. Chame `PFAuthenticationLoginWithXUserAsync`: * Passe o `XUserHandle` como o parâmetro `user`. * Defina `createAccount = TRUE` para que o PlayFab provisione automaticamente uma conta vinculada na primeira entrada. 3. Mantenha as credenciais do PlayFab resultantes (Entity ID + token do PlayFab) durante a sessão e use-as em todas as chamadas subsequentes do PlayFab. Veja o [Início rápido do PlayFab Services SDK para GDK](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart) para obter o passo a passo completo. ### PlayFab Party XBOX Live Helper Library Se o PlayFab Party for o **único** serviço do PlayFab que seu título usa, você poderá dispensar o PlayFab Services SDK e entrar por meio da Party XBOX Live Helper Library, que vem incluída com o SDK do PlayFab Party no GDK. **Fluxo** 1. Conecte o jogador ao XBOX com `XUserAddAsync`. 2. Quando o chat for iniciado pela primeira vez, recupere o XUID com `XUserGetId`. 3. Crie um **`PartyXblLocalChatUser`** chamando `PartyXblManager::CreateLocalChatUser` com o XUID. 4. Chame `PartyXblManager::LoginToPlayFab` com esse objeto de usuário. * No GDK (console e PC) e no XDK, a biblioteca auxiliar busca internamente o token necessário dos serviços XBOX, conecta o jogador ao PlayFab usando as credenciais do XBOX e cria automaticamente uma conta do PlayFab na primeira entrada. As contas criadas dessa forma não têm e-mail nem nome de usuário associados. * Em títulos que não são GDK/XDK (por exemplo, PC Win32 sem GDK), você recebe um `PartyXblTokenAndSignatureRequestedStateChange`. Busque você mesmo o token dos serviços XBOX e devolva-o por meio de `PartyXblManager::CompleteGetTokenAndSignatureRequest`. 5. Em caso de sucesso, você recebe um `PartyXblLoginToPlayFabCompletedStateChange` contendo a Entity ID e o token do PlayFab. > [!NOTE] > > Para usuários **remotos**, use `PartyXblManager::CreateRemoteChatUser`; nenhuma autenticação ou troca de token é necessária no fluxo de usuário remoto. ## O XUser é a ponte de identidade Tudo o que vem depois (entrada no PlayFab, tokens de gravação de sessão MPSD, chamadas S2S, consultas de direitos) começa com um `XUserHandle` retornado por `XUserAddAsync`. Duas APIs são importantes para a integração do PlayFab: | API | Finalidade | | - | - | | [`XUserAddAsync`](https://docs.xbox.com/pt-BR/reference/system/xuser/xuser_members) | Conecta o jogador à conta XBOX e obtém um `XUserHandle`. | | `XUserGetTokenAndSignatureUtf16Async` | Recupera um token + assinatura dos serviços XBOX para o caminho da biblioteca auxiliar (fallback do Win32) ou para qualquer ponte S2S personalizada. | Veja [Identidade dos serviços XBOX](https://docs.xbox.com/pt-BR/services/xbox-services/fundamentals/identity/xs-identity-overview.md) para conhecer o modelo de entrada mais amplo (MSA, tokens XSTS, escopo de sandbox). ## Títulos multiplataforma O PlayFab dá suporte a muitos provedores de autenticação de plataforma. Ao lançar o mesmo título em iOS, Android, Steam ou PlayStation, **não** tente direcionar todos os jogadores pelo XUser; use o provedor de autenticação nativo do PlayFab da plataforma: * **iOS** — Apple ID (`LoginWithApple`). * **Android** — Google Play Games (`LoginWithGoogleAccount`). * **Steam** — `LoginWithSteam`. * **XBOX / GDK PC**: `PFAuthenticationLoginWithXUserAsync` (esta página). Cada entrada de plataforma provisiona a própria conta do PlayFab e a vincula ao mesmo título do PlayFab. Os jogadores que mudam de plataforma com a mesma conta do PlayFab têm suas identidades vinculadas mescladas dentro do PlayFab. Veja [Autenticação do PlayFab específica da plataforma](https://learn.microsoft.com/gaming/services/playfab/features/authentication/platform-specific-authentication/) para obter a matriz completa. ## Compras no aplicativo da Microsoft Store por meio da economia do PlayFab Para títulos GDK que vendem itens no aplicativo pela Microsoft Store, o PlayFab atua como **back-end de economia**, enquanto a Microsoft Store processa a transação real. O PlayFab reconcilia as compras da Microsoft Store no inventário do PlayFab do jogador usando o **método de direitos**; o jogador deve estar conectado primeiro à conta XBOX. ### O fluxo 1. O jogador está conectado ao XBOX (`XUserAddAsync`) e ao PlayFab (`PFAuthenticationLoginWithXUserAsync`). 2. O jogador compra um item pela Microsoft Store no dispositivo. 3. Seu título notifica o PlayFab sobre a compra. 4. O PlayFab chama [`ConsumeMicrosoftStoreEntitlements`](https://learn.microsoft.com/rest/api/services/playfab/client/platform-specific-methods/consume-microsoft-store-entitlements) com o token do XBOX e sincroniza o inventário do PlayFab do jogador, concedendo os novos itens. > [!WARNING] > > Para títulos GDK, use o complemento **Microsoft Store** do PlayFab e `ConsumeMicrosoftStoreEntitlements`. **Não** use o complemento XBOX herdado / `ConsumeXboxEntitlements` (esse caminho é somente para títulos XDK). O complemento da Plataforma Universal do Windows foi preterido. ### Pré-requisitos do Partner Center * Estar inscrito no [XBOX Creators Program](https://www.xbox.com/developers/creators-program) ou ser um Managed Partner. * Identidade do editor configurada no Partner Center com o mesmo GUID de editor das informações de parceiro comercial do XBOX (`aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`). * Aprovação de conceito para usar os serviços XBOX. No Partner Center, em **Game setup → XBOX services**, escolha **Use full XBOX services feature set (requires concept approval)** ou **Use XBOX Creators Program** e, em seguida, crie seus complementos no seu título. > [!NOTE] > > O complemento Microsoft Store do PlayFab **não dá suporte a consumíveis gerenciados pela loja** no Partner Center. Crie somente **consumíveis gerenciados pelo desenvolvedor** (ou duráveis). ### Criar itens correspondentes no Partner Center e no PlayFab A **Product ID** no Partner Center e a **Item ID** no PlayFab devem corresponder exatamente para que a sincronização de direitos funcione. 1. No Partner Center → **Add-ons** → **Create a new Consumable (Developer-managed)** (ou Durable). Insira uma **Product ID** exclusiva (por exemplo, `MyItem_001`). 2. No [PlayFab Game Manager](https://developer.playfab.com/) → **Engage** → **Economy** → **New item**. Insira a mesma string em **Item ID** (`MyItem_001`). Marque-o como Consumable ou Durable para corresponder ao Partner Center e salve. ### Referência de terminologia | Conceito | PlayFab | Partner Center / Microsoft Store | | - | - | - | | Identificador exclusivo | Item ID | Product ID | | Consumable | Consumable | Consumable (Developer-managed) | | Durable | Durable | Durable *ou* Durable with packages | | Loja virtual no jogo | Store | *(n/a)* | ### Catálogos e lojas: uma Item ID global O PlayFab permite definir vários **Catalogs** por título e, dentro de cada Catalog, você pode agrupar itens em **Stores**. Para que a sincronização de direitos da Microsoft Store funcione, **cada Product ID deve corresponder a exatamente uma Item ID em todas as versões de Catalog do seu título do PlayFab.** > [!WARNING] > > Se a mesma `Item ID` aparecer em mais de um Catalog, o consumo de direitos falhará. Mantenha as IDs de item globalmente exclusivas em todos os Catalogs de um determinado título do PlayFab. **Errado: a mesma ID reutilizada em vários catálogos:** | Versão do catálogo | Item ID | Tipo | | - | - | - | | MyCatalog\_001 | MyItem\_001 | Consumable | | MyCatalog\_002 | MyItem\_001 | Consumable | | MyCatalog\_003 | MyItem\_001 | Durable | **Certo: uma Item ID por SKU, reutilizada livremente entre Stores:** | Versão do catálogo | Item ID | Tipo | | - | - | - | | MyCatalog\_001 | MyItem\_001 | Consumable | | MyCatalog\_001 | MyItem\_002 | Durable | | MyCatalog\_002 | MyItem\_003 | Consumable | | MyCatalog\_003 | MyItem\_004 | Durable | As Stores dentro de um Catalog podem então agrupar livremente qualquer subconjunto desses itens exclusivos: | ID da Store | IDs de item | | - | - | | MyStore\_001 | MyItem\_001, MyItem\_002 | | MyStore\_002 | MyItem\_001 | | MyStore\_003 | MyItem\_002, MyItem\_003, MyItem\_004 | ## Veja também * [Identidade dos serviços XBOX](https://docs.xbox.com/pt-BR/services/xbox-services/fundamentals/identity/xs-identity-overview.md): XUser, MSA, tokens XSTS, escopo de sandbox. * [Multijogador do XBOX](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/index.md): PlayFab Party como opção de transporte multijogador. * [Game Chat 2](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro.md): Game Chat 2 em camada sobre o PlayFab Party. * [Multiplayer Activity](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpa/live-mpa-overview.md): integração de MPA + PlayFab Party. * [Início rápido do PlayFab Services SDK para GDK](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart) * [Preços do PlayFab](https://playfab.com/pricing/) ## Related topics - [Identity](https://docs.xbox.com/pt-BR/xbox-services/identity.md) - [Multiplayer](https://docs.xbox.com/pt-BR/xbox-services/multiplayer.md) - [Game Chat](https://docs.xbox.com/pt-BR/xbox-services/game-chat.md) - [Multiplayer Activity](https://docs.xbox.com/pt-BR/xbox-services/multiplayer-activity.md)