Migrar do SDK autônomo v1 do PlayFab para o SDK unificado v2

​

Visão geral das alterações

• Arquitetura unificada: todos os serviços do PlayFab (Core, Services, Party, Multiplayer, GameSave) são integrados em um único SDK
• Autenticação simplificada: um único logon dá acesso a todos os serviços do PlayFab por meio de identificadores de entidade
• Gerenciamento automático de tokens: chega de atualização manual de tokens ou de gerenciamento de IDs de entidade
• Interoperabilidade aprimorada: comunicação perfeita entre os diferentes serviços do PlayFab
• Estrutura de projeto simplificada: uma única instalação de SDK em vez de vários pacotes separados

​

Alterações na estrutura do projeto

​

Para usuários do GDK

• Extensões separadas para cada componente do SDK
• Pastas de inclusão e de bibliotecas individuais: PlayFab.Services.Cpp, PlayFab.Party.Cpp, PlayFab.Multiplayer.Cpp
• Cada serviço tinha nomes de ExtensionLibrary distintos no GDK
• Vários downloads necessários para os diferentes serviços do PlayFab no GitHub

• Um único SDK unificado do PlayFab
• Estrutura organizada por plataforma, com subpastas (xbox, windows etc.)
• Todos os cabeçalhos consolidados em uma única pasta de inclusão (Core, Services, Multiplayer, Party, GameSave)
• Bibliotecas combinadas em uma pasta lib unificada

​

Atualizando as referências do projeto

1. Remova as referências antigas: exclua as referências a PlayFab.Services.Cpp, PlayFab.Party.Cpp e outras extensões de SDK individuais
2. Adicione a referência unificada: faça referência ao novo SDK unificado do PlayFab ou atualize os caminhos de inclusão/bibliotecas para os locais unificados
3. Planeje para o futuro: a Microsoft removerá as pastas antigas em versões futuras do GDK (possivelmente até 2026), portanto atualize os arquivos de projeto adequadamente

​

Para usuários do GitHub/autônomos

• Substitua vários downloads de SDK pelo pacote único do SDK unificado
• Atualize os caminhos do projeto para usar a nova estrutura de pastas organizada por plataforma

​

Autenticação e tratamento de entidades

​

Alterações no gerenciamento de tokens

• Recuperação manual de tokens usando PFAuthenticationGetEntityTokenAsync
• Atualização manual dos tokens quando eles expiram
• Passagem de cadeias de caracteres de ID de entidade e token para outros serviços (por exemplo, partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser))

• Gerenciamento automático de tokens pelo SDK Core
• Atualização de tokens em segundo plano antes da expiração
• Passagem de PFEntityHandle diretamente para outros serviços (por exemplo, partyManager.CreateLocalUser(entityHandle, &localUser))

​

Etapas de migração da autenticação

1. Remova o gerenciamento manual de tokens: exclua o código que recupera ou verifica manualmente os tokens do PlayFab
2. Armazene os identificadores de entidade: mantenha o PFEntityHandle do logon e use-o em todos os serviços do PlayFab
3. Atualize as chamadas de serviço: substitua os parâmetros de ID de entidade/token por identificadores de entidade
4. Trate a reautenticação: use as APIs PFAuthenticationReLogin*Async em cenários de reautenticação

​

Alterações interruptivas na API por componente

​

PlayFab Core

• A maioria das chamadas de serviço do Core permanece inalterada
• Atualize os caminhos de inclusão para apontar para os cabeçalhos do SDK unificado

​

PlayFab Services

• A maioria das chamadas do Services permanece inalterada
• Atualize os caminhos de inclusão para apontar para os cabeçalhos do SDK unificado

​

PlayFab Party (rede/voz)

​

Alterações na inicialização

PartyManager& partyManager = PartyManager::GetSingleton();
PartyError err = partyManager.Initialize("YOUR_PLAYFAB_TITLE_ID");

PartyManager& partyManager = PartyManager::GetSingleton();

PartyInitializationConfiguration partyInitConfig = {};
partyInitConfig.titleId = "YOUR_PLAYFAB_TITLE_ID";
partyInitConfig.audioTaskQueue = nullptr;
partyInitConfig.networkingTaskQueue = nullptr;

PartyError err = partyManager.Initialize(&partyInitConfig);

​

Alterações na criação de usuários locais

PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser);

PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityHandle, &localUser);

​

Etapas de migração do Party

1. Atualize a inicialização: substitua a chamada simples a PartyManager::Initialize() pela abordagem com struct de configuração
2. Remova a recuperação de tokens: exclua qualquer código que obtenha manualmente o ID de entidade/token para o Party
3. Passe identificadores de entidade: use PFEntityHandle diretamente em vez de parâmetros de cadeia de caracteres
4. Remova a lógica de atualização de tokens: exclua o código que verifica ou atualiza periodicamente os tokens do Party
5. Atualize as dependências: garanta que o PlayFab Core seja inicializado antes de PartyManager::Initialize()
6. Remova chamadas específicas do XBOX: substitua PartyXblManagerInitialize() pelo PartyInitialize() genérico no XBOX

​

PlayFab Multiplayer (Lobby e Matchmaking)

​

Alterações nas operações de lobby

PFEntityKey newMember{ entityId, entityType };
HRESULT hr = PFMultiplayerJoinLobby(pfmHandle, &newMember, connectionString, &joinConfig, nullptr, &lobby);

HRESULT hr = PFMultiplayerJoinLobbyWithEntityHandle(pfmHandle, entityHandle, connectionString, &joinConfig, nullptr, &lobby);

​

Etapas de migração do Multiplayer

1. Atualize as chamadas de função: substitua os parâmetros de ID do PlayFab e token de entidade por PFEntityHandle
2. Remova as etapas de autenticação: exclua as chamadas separadas de “Authenticate Multiplayer”
3. Inicialize explicitamente: chame PFMultiplayerInitialize() e, possivelmente, PFMultiplayerStartProcessing()
4. Atualize o matchmaking: use identificadores de entidade na criação de tíquetes de matchmaking

​

Lista de verificação geral da migração

​

Atualizações de código

• Atualize os caminhos de inclusão: aponte para o diretório de inclusão do SDK unificado
• Atualize a vinculação de bibliotecas: vincule as bibliotecas unificadas em vez das separadas
• Remova funções preteridas: exclua as chamadas a funções removidas, como PartyManager::CreateLocalUserWithEntityType
• Substitua o gerenciamento manual de tokens: remova a lógica de cache e atualização de tokens
• Atualize a ordem de inicialização: garanta que o PlayFab Core seja inicializado antes dos outros serviços

​

Lista de verificação de testes

• Autenticação: o logon retorna um identificador de entidade válido
• Operações de lobby: criar/ingressar em lobbies funciona corretamente
• Rede do Party: os jogadores conseguem se conectar e se comunicar entre máquinas
• Tratamento de erros: todas as chamadas do PlayFab tratam os erros adequadamente
• Cenários com vários usuários: vários usuários locais funcionam, se aplicável

​

Problemas comuns e soluções

• Verifique se as assinaturas de função mudaram para exigir PFEntityHandle
• Certifique-se de passar o identificador de entidade em vez de IDs em cadeia de caracteres

• Verifique se o PlayFab Core é inicializado antes dos outros serviços
• Verifique se o logon é concluído antes de criar usuários locais no Party/Multiplayer

• São raras, mas verifique se a v2 não introduz problemas em caminhos de código críticos para o desempenho

​

Benefícios da migração

​

Simplificação do código

• Complexidade reduzida: remova o código de contorno criado para a separação de serviços da v1
• Tratamento de erros unificado: todos os serviços do PlayFab usam relatórios de erro consistentes
• Autenticação centralizada: um único fluxo de logon para todos os recursos do PlayFab

​

Interoperabilidade aprimorada

• Integração perfeita: adicionar novos recursos do PlayFab exige configuração mínima
• Melhor suporte a vários usuários: o SDK unificado lida com vários usuários locais de forma mais eficaz
• Modelo de entidades consistente: a mesma abordagem de autenticação em todos os serviços

​

Preparação para o futuro

• Desenvolvimento ativo: a v2 é a versão mantida ativamente
• Novos recursos: os recursos futuros do PlayFab serão direcionados ao SDK unificado
• Suporte de longo prazo: os SDKs v1 acabarão sendo preteridos

​

Próximas etapas

1. Atualize a estrutura do projeto: migre para a estrutura do SDK unificado
2. Refatore a autenticação: implemente a abordagem baseada em identificadores de entidade
3. Teste minuciosamente: valide se toda a funcionalidade do PlayFab funciona corretamente
4. Limpe o código: remova os contornos preteridos da v1 e o gerenciamento manual de tokens
5. Monitore o desempenho: garanta que a migração não introduza problemas de desempenho