> ## 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. # Migrar do SDK autônomo v1 do PlayFab para o SDK unificado v2 > Migre um título do PlayFab dos SDKs autônomos v1 para o SDK unificado v2, abrangendo as alterações na estrutura do projeto, na autenticação e no gerenciamento de tokens. Este guia ajuda você a migrar dos SDKs v1 mais antigos do PlayFab para o novo SDK unificado v2 do PlayFab. O SDK unificado consolida SDKs que antes eram separados (Core, Services, Party, Multiplayer) em uma única solução integrada, com interoperabilidade aprimorada e autenticação simplificada. ## Visão geral das alterações O SDK unificado v2 do PlayFab introduz várias melhorias importantes: * **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 **Estrutura herdada (GDK 2504 e anteriores):** * 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 **Nova estrutura (GDK 2510 em diante):** * 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 Durante o período de transição (GDK 2510), os SDKs antigos e novos coexistem. Para migrar: 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 O conceito de entidades e tokens de entidade existe nas duas versões, mas a forma de usá-los foi simplificada na v2. ### Alterações no gerenciamento de tokens **Abordagem dos SDKs autônomos do PlayFab (v1):** * 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)`) **Abordagem do SDK unificado do PlayFab (v2):** * 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 **Impacto da migração**: alterações mínimas necessárias * 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 **Impacto da migração**: alterações mínimas necessárias * 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) **Impacto da migração**: pequenas alterações necessárias #### Alterações na inicialização **Inicialização na v1:** ```cpp theme={null} PartyManager& partyManager = PartyManager::GetSingleton(); PartyError err = partyManager.Initialize("YOUR_PLAYFAB_TITLE_ID"); ``` **Inicialização na v2:** ```cpp theme={null} 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 **Abordagem da v1:** ```cpp theme={null} PartyLocalUser* localUser = nullptr; PartyError err = partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser); ``` **Abordagem da v2:** ```cpp theme={null} 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) **Impacto da migração**: pequenas alterações necessárias Os conceitos principais (Lobby, tíquete de matchmaking) permanecem os mesmos, mas as funções agora esperam identificadores de entidade em vez de cadeias de caracteres. #### Alterações nas operações de lobby **Abordagem da v1:** ```cpp theme={null} PFEntityKey newMember{ entityId, entityType }; HRESULT hr = PFMultiplayerJoinLobby(pfmHandle, &newMember, connectionString, &joinConfig, nullptr, &lobby); ``` **Abordagem da v2:** ```cpp theme={null} 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 Após a migração, verifique cada subsistema: * [ ] **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 **Erros do compilador sobre parâmetros ausentes**: * 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 **Falhas de autenticação em tempo de execução**: * 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 **Regressões de desempenho**: * 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 Para obter ajuda adicional, consulte a documentação e os exemplos do SDK unificado do PlayFab para a sua plataforma específica. ## Related topics - [Produtos de SDK do PlayFab](/pt-BR/services/playfab/sdks/sdk-products.md) - [SDK unificado do PlayFab](/pt-BR/services/playfab/sdks/unified-sdk/overview.md) - [Configuração do início rápido do SDK unificado do PlayFab](/pt-BR/services/playfab/sdks/unified-sdk/quickstart-setup.md) - [Rastreamento de depuração no SDK unificado do PlayFab](/pt-BR/services/playfab/sdks/unified-sdk/debug-trace.md) - [Fazendo chamadas assíncronas no SDK unificado do PlayFab](/pt-BR/services/playfab/sdks/unified-sdk/async-model.md)