Integração do PlayFab para títulos dos serviços XBOX

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.

​

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

​

Conectar jogadores ao PlayFab

Há dois caminhos de entrada com suporte. Escolha um com base nos serviços do PlayFab que você usa:

​

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

​

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: Veja Identidade dos serviços XBOX 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 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 com o token do XBOX e sincroniza o inventário do PlayFab do jogador, concedendo os novos itens.

​

Pré-requisitos do Partner Center

• Estar inscrito no XBOX 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.

​

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 → 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

​

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. Errado: a mesma ID reutilizada em vários catálogos: Certo: uma Item ID por SKU, reutilizada livremente entre Stores: As Stores dentro de um Catalog podem então agrupar livremente qualquer subconjunto desses itens exclusivos:

​

Veja também

• Identidade dos serviços XBOX: XUser, MSA, tokens XSTS, escopo de sandbox.
• Multijogador do XBOX: PlayFab Party como opção de transporte multijogador.
• Game Chat 2: Game Chat 2 em camada sobre o PlayFab Party.
• Multiplayer Activity: integração de MPA + PlayFab Party.
• Início rápido do PlayFab Services SDK para GDK
• Preços do PlayFab