Estratégias de vinculação de contas para o PlayFab Game Saves

​

Identidade de vinculação principal

1. Estar disponível para os jogadores em todas as plataformas nas quais eles possam jogar o jogo
2. Ter suporte de uma chamada de login existente do PlayFab, como LoginWithXbox ou LoginWithOpenIdConnect

​

Identidade nativa da plataforma

• Steam: conta da Steam e tíquete de autenticação (ISteamUser::GetAuthTicketForWebApi)
• XBOX no PC/console: XUserHandle da MSA/XBOX e token XSTS
• PlayStation: ID online/conta da PSN
• Nintendo: Nintendo Service Account/ID do dispositivo

​

Opções de estratégia de vinculação

1. Todos os jogadores são obrigados a vincular sua identidade nativa da plataforma à sua identidade de vinculação principal antes de jogar.
2. A vinculação entre a identidade nativa da plataforma e a identidade de vinculação principal é opcional, mas fortemente incentivada antes de jogar.

​

Estado desejado

​

LocalUser versus login

​

Estratégia 1: vinculação obrigatória da identidade principal

​

Resumo de alto nível

• O jogador deve entrar com a identidade entre plataformas (XBOX/MSA) antes de jogar.
• Crie um jogador local a partir da conta da plataforma (Steam), mas suspenda o jogo online até que a entrada com XBOX/MSA seja concluída.
• Após a entrada com XBOX/MSA, vincule a conta da plataforma à conta entre plataformas.
• Atualize o perfil local da plataforma para que ele fique conectado à conta entre plataformas.
• As próximas inicializações são contínuas: o jogador pode ir direto para o jogo porque o vínculo está estabelecido.

​

Passo a passo detalhado

• Chame PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, customContext, outLocalUserHandle).
• Resultado: PFLocalUserHandle; ainda sem autenticação.

• Chame PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ false, async).
• Na conclusão, se PFLocalUserLoginGetResult falhar com E_PF_ACCOUNT_NOT_FOUND, dispare a entrada com o XBOX para inicializar a conta.
• Se PFLocalUserLoginGetResult tiver êxito, já temos uma conta no estado desejado e ela está online. Fluxo de trabalho concluído.

• Crie PFAuthenticationLoginWithXUserRequest:
  • Defina createAccount=true para criar a conta do PlayFab, se necessário.
  • Forneça o XUserHandle do seu usuário XBOX conectado no PC.
• Chame PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, request, async).
• Conclua com PFAuthenticationLoginWithXUserGetResultSize(...) e PFAuthenticationLoginWithXUserGetResult(...) para obter PFEntityHandle.
• Observação: use PFAuthenticationLoginWithXbox se a variante LoginWithXUser não estiver disponível. Isso exige que você mesmo extraia o token XSTS do XUserHandle.

• Crie uma solicitação de vínculo de cliente com o tíquete de autenticação atual da Steam (de ISteamUser::GetAuthTicketForWebApi ou equivalente na sua integração; confirme o nome exato da função no seu código).
• Chame PFAccountManagementClientLinkSteamAccountAsync(entityHandle, linkRequest, async).
• Observação: “LinkSteamAccount” fica em Account Management, não em Authentication.
• Após o êxito, a identidade da Steam do jogador estará vinculada à conta do PlayFab baseada no XBOX.

• Chame PFLocalUserLoginAsync(steamLocalUserHandle, /*createAccount*/ false, async) novamente.
• PFLocalUserLoginGetResult agora tem êxito; o PFEntityHandle resultante fica associado ao usuário local da Steam.

• O Game Save e outras APIs online usam o PFEntityHandle autenticado.
• As próximas inicializações do jogo podem ir direto para o jogo, pois toda a vinculação está estabelecida.

• PFLocalUserCreateHandleWithSteamUser não faz login sozinho, mas tentar chamar PFGameSaveFilesAddUserWithUiAsync resulta em uma tentativa de login. Verifique se você passou pelo fluxo de vinculação de contas antes dessa chamada.

​

Tratamento de conflitos de vínculo

• Após a entrada com o XBOX, chame PFAccountManagementClientGetAccountInfoAsync(xboxEntity, getInfoRequest, async) para buscar as informações da conta e inspecionar as identidades vinculadas.
• Se a entidade já tiver uma conta da Steam diferente vinculada:
  • Avise o jogador que prosseguir removerá a antiga associação da Steam desta entidade. Obtenha o consentimento.
  • Chame PFAccountManagementClientUnlinkSteamAccountAsync(xboxEntity, unlinkRequest, async) para remover o vínculo existente da Steam.
  • Em seguida, chame PFAccountManagementClientLinkSteamAccountAsync com o tíquete atual da Steam.
• Se a chamada de vínculo retornar E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED (a conta da Steam pertence a outra entidade):
  • Avise o jogador que esta conta da Steam está associada a uma conta do PlayFab diferente e que vinculá-la aqui removerá essa associação.
  • Tente novamente com forceLink=true após o consentimento.

​

Exemplo de fluxo em C++ (bloqueio inicial com Steam, inicialização com XBOX, vinculação da Steam, novo login com Steam):

// Assumes: serviceConfigHandle, taskQueue, and a signed-in XUserHandle (xUserHandle) are available
//
// NOTE: RETURN_IF_FAILED is used here for brevity. Because XAsyncBlock callbacks return void,
// production code should replace it with proper error handling (for example, log and return).

// Single context block used by multiple nested callbacks
struct Strategy1AsyncCtx
{
    PFServiceConfigHandle serviceConfig{};
    XTaskQueueHandle queue{};
    PFLocalUserHandle steamUser{};
    XUserHandle xUserHandle{};
    PFEntityHandle xboxEntity{};
};

// 1) Create Steam local user
PFLocalUserHandle steamUser{};
RETURN_IF_FAILED(PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, /*customContext*/ nullptr, &steamUser));

// 2) Attempt Steam login with createAccount=false
XAsyncBlock steamLoginAsync{};
steamLoginAsync.queue = taskQueue;
// Provide context for nested callbacks
// NOTE: Caller is responsible for deleting s1ctx in the terminal callback.
Strategy1AsyncCtx* s1ctx = new Strategy1AsyncCtx{ serviceConfigHandle, taskQueue, steamUser, xUserHandle };
steamLoginAsync.context = s1ctx;
steamLoginAsync.callback = [](XAsyncBlock* async)
{
    auto* ctx = static_cast<Strategy1AsyncCtx*>(async->context);
    // Try to get result-size; failure means login failed
    size_t bufferSize{};
    HRESULT hrSize = PFLocalUserLoginGetResultSize(async, &bufferSize);
    if (FAILED(hrSize))
    {
        if (hrSize == E_PF_ACCOUNT_NOT_FOUND)
        {
            // 3) Bootstrap via Xbox (provider API), then link Steam
            PFAuthenticationLoginWithXUserRequest xreq{};
            xreq.createAccount = true;
            xreq.user = ctx->xUserHandle; // supply your signed-in XUserHandle

            static XAsyncBlock xboxLoginAsync{}; // ensure lifetime until callback
            xboxLoginAsync.queue = async->queue;
            xboxLoginAsync.context = ctx;
            xboxLoginAsync.callback = [](XAsyncBlock* xAsync)
            {
                auto* ctx = static_cast<Strategy1AsyncCtx*>(xAsync->context);
                // Obtain Xbox login result
                PFEntityHandle xboxEntity{};
                size_t xSize{};
                RETURN_IF_FAILED(PFAuthenticationLoginWithXUserGetResultSize(xAsync, &xSize));
                std::vector<uint8_t> xbuf(xSize);
                PFAuthenticationLoginResult const* xres{};
                RETURN_IF_FAILED(PFAuthenticationLoginWithXUserGetResult(xAsync, &xboxEntity, xbuf.size(), xbuf.data(), &xres, nullptr));
                ctx->xboxEntity = xboxEntity;

                // Detect existing Steam linkage before linking
                // Build a minimal GetAccountInfo request
                // Then call PFAccountManagementClientGetAccountInfoAsync(xboxEntity, &getInfoReq, &getInfoAsync)
                // and inspect the linked accounts section of the result.
                //
                // If the entity already has a DIFFERENT Steam account linked:
                //   Call PFAccountManagementClientUnlinkSteamAccountAsync(xboxEntity, &unlinkReq, &unlinkAsync)
                //   to remove the old Steam link, then proceed to link the current Steam account below.
                //   forceLink does NOT resolve this case (E_PF_ACCOUNT_ALREADY_LINKED error).
                //
                // If a DIFFERENT entity has this Steam account claimed:
                //   The link call below will fail with E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED.
                //   Retry with forceLink=true after obtaining player consent.

                // Link Steam to Xbox-backed account
                PFAccountManagementClientLinkSteamAccountRequest linkReq{};
                linkReq.steamTicket = GetCurrentSteamTicket(); // your helper wrapping ISteamUser::GetAuthTicketForWebApi
                bool isServiceSpecific = true;
                linkReq.ticketIsServiceSpecific = &isServiceSpecific;
                // To resolve E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED after consent:
                // bool forceLink = true;
                // linkReq.forceLink = &forceLink;

                static XAsyncBlock linkAsync{};
                linkAsync.queue = xAsync->queue;
                linkAsync.context = ctx;
                linkAsync.callback = [](XAsyncBlock* linkXAsync)
                {
                    auto* ctx = static_cast<Strategy1AsyncCtx*>(linkXAsync->context);
                    RETURN_IF_FAILED(XAsyncGetStatus(linkXAsync, false));

                    // 4) Re-login Steam local user to bind entity handle
                    static XAsyncBlock steamReloginAsync{};
                    steamReloginAsync.queue = linkXAsync->queue;
                    steamReloginAsync.context = ctx;
                    steamReloginAsync.callback = [](XAsyncBlock* reloginAsync)
                    {
                        auto* ctx = static_cast<Strategy1AsyncCtx*>(reloginAsync->context);
                        PFEntityHandle entity{};
                        RETURN_IF_FAILED(PFLocalUserLoginGetResult(reloginAsync, &entity, 0, nullptr, nullptr, nullptr));
                        // Now the Steam local user has an associated entity
                    };

                    RETURN_IF_FAILED(PFLocalUserLoginAsync(ctx->steamUser, /*createAccount*/ false, &steamReloginAsync));
                };

                RETURN_IF_FAILED(PFAccountManagementClientLinkSteamAccountAsync(ctx->xboxEntity, &linkReq, &linkAsync));
            };

            // NOTE: On platforms that don't support LoginWithXUser, replace this with PFAuthenticationLoginWithXboxAsync
            RETURN_IF_FAILED(PFAuthenticationLoginWithXUserAsync(ctx->serviceConfig, &xreq, &xboxLoginAsync));
        }
        // Other failures: handle/log as needed
        return;
    }

    // Steam login succeeded: get entity
    PFEntityHandle entity{};
    RETURN_IF_FAILED(PFLocalUserLoginGetResult(async, &entity, 0, nullptr, nullptr, nullptr));
    // Use entity as needed; PFServices/GameSave APIs, etc.
};

RETURN_IF_FAILED(PFLocalUserLoginAsync(steamUser, /*createAccount*/ false, &steamLoginAsync));

• Use E_PF_ACCOUNT_NOT_FOUND para decidir o caminho de inicialização com o XBOX; trate os outros erros separadamente.
• Continue usando o PFLocalUserHandle da Steam; o login específico do provedor XBOX retorna um entityHandle usado apenas para vincular a Steam.
• Após a vinculação, faça login com a Steam novamente para associar a entidade ao LocalUser.
• Obtenha um tíquete novo da Steam para a vinculação.
• Feche os identificadores quando não forem mais necessários (PFLocalUserCloseHandle, PFEntityCloseHandle).

​

Estratégia 2: vinculação opcional da identidade principal

​

Resumo de alto nível

• Crie um jogador local usando a conta da plataforma (Steam) e tente jogar online sem criar uma nova conta.
• Se o modo online funcionar, continue; caso contrário, ofereça uma escolha:
  • Entrar com a identidade entre plataformas (XBOX/MSA) para criar uma conta unificada, ou
  • Criar agora uma conta somente da plataforma e começar a jogar imediatamente.
• Incentive a vinculação antecipada ao XBOX/MSA explicando os benefícios e os riscos.
• Quando o jogador optar por vincular:
  • Se a vinculação tiver êxito diretamente, continue jogando com uma conta unificada.
  • Se a conta XBOX/MSA já tiver progresso em outro lugar, pause e pergunte qual progresso manter (reconciliação):
    • Manter o progresso do XBOX/MSA e anexar a conta atual da plataforma.
    • Manter o progresso atual da plataforma e adiar a vinculação.
• Após a vinculação, atualize o perfil local da plataforma para que ele fique conectado à conta unificada.
• As próximas inicializações são contínuas: o jogador pode ir direto para o jogo (supondo que a vinculação não tenha sido adiada).

​

Passo a passo detalhado

• Chame PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, customContext, outLocalUserHandle).
• Resultado: PFLocalUserHandle; ainda sem autenticação.

• Chame PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ false, async).
• Na conclusão:
  • Se PFLocalUserLoginGetResult tiver êxito, use o PFEntityHandle resultante e prossiga online.
    • Verifique se a conta baseada na Steam já está vinculada ao XBOX/MSA. Chame PFAccountManagementClientGetAccountInfoAsync(entityHandle, getInfoRequest, async) e inspecione as identidades vinculadas. Se não estiver vinculada, solicite que o jogador vincule o XBOX usando o fluxo abaixo (sem bloqueio), para que a progressão entre plataformas futura funcione perfeitamente.
  • Se PFLocalUserLoginGetResult falhar com E_PF_ACCOUNT_NOT_FOUND, o jogador permanecerá offline até que uma conta seja criada. Ofereça duas opções:
    • Criar agora uma conta do PlayFab baseada no XBOX: entrar com XBOX/MSA (por exemplo, PFAuthenticationLoginWithXUserAsync).
    • Entrar com a Steam agora e começar a jogar: chame PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ true, async) para criar uma conta do PlayFab baseada na Steam associada ao identificador local; em caso de êxito, use o PFEntityHandle resultante para prosseguir online imediatamente.
  • Para outros erros, trate-os adequadamente (nova tentativa/retirada).

• Apresente os benefícios da vinculação (progressão entre plataformas, portabilidade dos direitos).
• Ofereça a entrada com XBOX/MSA.

• Se o jogador estiver iniciando a vinculação do XBOX mais tarde (ele já tem um PFEntityHandle baseado na Steam da sessão atual):
  • Não crie uma nova conta baseada no XBOX.
  • Tente vincular a identidade XBOX diretamente à conta atual baseada na Steam chamando a API de vínculo apropriada (por exemplo, PFAccountManagementClientLinkXboxAccountAsync(currentSteamEntity, linkRequest, async)).
  • Se a vinculação tiver êxito, a identidade XBOX/MSA agora estará vinculada; continue a operação normal.
  • Se a vinculação falhar com um erro de vínculo/conflito preexistente (identidade XBOX já vinculada em outro lugar), entre no modo de reconciliação de contas. Execute imediatamente a entrada com XBOX/MSA com createAccount=false (por exemplo, PFAuthenticationLoginWithXUserAsync) para obter o PFEntityHandle baseado no XBOX e, em seguida, busque os metadados do perfil para dar contexto antes de perguntar ao jogador. Após o consentimento, prossiga para as decisões de vinculação.
• Se o jogador não tiver uma conta existente para o XBOX (caminho de inicialização):
  • Primeiro, tente entrar com XBOX/MSA com createAccount=false usando PFAuthenticationLoginWithXUserAsync (ou PFAuthenticationLoginWithXboxAsync, quando LoginWithXUser não estiver disponível).
    • Se a entrada tiver êxito: a conta XBOX/MSA já tem uma conta do PlayFab e provavelmente progresso existente. Entre no modo de reconciliação de contas para escolher qual progresso manter.
    • Se a entrada falhar com E_PF_ACCOUNT_NOT_FOUND: prossiga para criar a conta do PlayFab entrando novamente com createAccount=true.
  • Conclua com PFAuthenticationLoginWithXUserGetResultSize(...) e PFAuthenticationLoginWithXUserGetResult(...) para obter PFEntityHandle.

• Aplicável quando você acabou de criar uma nova conta do PlayFab baseada no XBOX (sem vínculos existentes da Steam).
• Se você entrou no modo de reconciliação de contas anteriormente, as decisões de vinculação e quaisquer ações de forceLink necessárias são tratadas lá; ignore esta etapa.
• Crie uma solicitação de vínculo de cliente com o tíquete de autenticação atual da Steam (de ISteamUser::GetAuthTicketForWebApi ou da sua integração).
• Chame PFAccountManagementClientLinkSteamAccountAsync(entityHandle, linkRequest, async) com forceLink=false (padrão). Espera-se que isso tenha êxito para uma conta nova.
• Se a vinculação falhar, trate isso como uma condição de erro (conflito inesperado ou falha de autenticação). Exiba um erro ao jogador e considere solicitar que ele entre novamente antes de tentar outra vez.
• Após o êxito, a identidade da Steam do jogador estará vinculada à conta do PlayFab baseada no XBOX.

• Chame PFLocalUserLoginAsync(steamLocalUserHandle, /*createAccount*/ false, async) novamente.
• PFLocalUserLoginGetResult agora tem êxito; o PFEntityHandle resultante fica associado ao usuário local da Steam.

• O Game Save e outras APIs online usam o PFEntityHandle autenticado.
• As próximas inicializações do jogo poderão ir direto para o jogo, pois toda a vinculação está estabelecida.

• Não bloqueie a jogabilidade inicial com a entrada com XBOX/MSA; solicite cedo, mas permita que os jogadores adiem.
• PFLocalUserCreateHandleWithSteamUser não faz login sozinho. Verifique se os fluxos de vinculação foram concluídos antes de chamar APIs que disparam o login, como PFGameSaveFilesAddUserWithUiAsync.

​

Reconciliação de contas (progresso existente no XBOX/MSA)

​

Fase de detecção

• A reconciliação pode ser iniciada por dois caminhos:
  1. Conta XBOX/MSA existente detectada: tente entrar com XBOX/MSA com createAccount=false.
     • Se a entrada tiver êxito, a identidade XBOX/MSA já tem uma conta do PlayFab e provavelmente progresso existente; entre na reconciliação.
     • Se a entrada falhar com E_PF_ACCOUNT_NOT_FOUND, prossiga com a inicialização (createAccount=true). Não é necessário entrar na reconciliação.
  2. Conflito de vinculação posterior detectado: ao vincular XBOX/MSA à conta atual baseada na Steam, a vinculação falha com um erro de vínculo/conflito preexistente (identidade XBOX já vinculada a uma identidade da Steam diferente).
     • Execute imediatamente a entrada com XBOX/MSA com createAccount=false (por exemplo, PFAuthenticationLoginWithXUserAsync) para obter o PFEntityHandle baseado no XBOX.
     • Busque os metadados do perfil (por exemplo, progressão recente, slots de salvamento, carimbos de data/hora) para apresentar o contexto.
     • Entre na reconciliação para decidir qual progresso manter.

​

Fase de reconciliação

• Recomende a opção direta: manter o progresso do XBOX/MSA (identidade de vinculação principal) e abandonar o progresso local da Steam. Isso preserva a âncora entre plataformas e evita mesclagens complexas.
• Na prática, os jogadores têm três opções (os jogos podem optar por oferecer apenas 1 ou 2 delas):
  1. Manter o progresso do XBOX/MSA (recomendado): prossiga para vincular a conta atual da Steam à conta do PlayFab existente baseada no XBOX.
  2. Manter o progresso atual da Steam e cancelar a vinculação: continue com a conta baseada na Steam por enquanto; não vincule nem substitua os dados do XBOX/MSA. Ofereça a vinculação novamente na próxima vez.
  3. Manter o progresso atual da Steam e abandonar o progresso do XBOX: mude para a conta baseada na Steam e descarte intencionalmente o progresso do XBOX/MSA. Esse caminho exige uma consideração explícita do design do jogo e não deve ser tentado levianamente, especialmente se outras identidades nativas da plataforma já estiverem anexadas à conta XBOX. Este documento não aborda os detalhes de implementação desse cenário.
• Antes de confirmar:
  • Chame PFAccountManagementClientGetAccountInfoAsync para a entidade XBOX para inspecionar os vínculos de provedores existentes e verificar se já existe um vínculo da Steam.
  • Se a entidade tiver uma conta da Steam diferente vinculada, avise o jogador que essa associação existente da Steam será removida da entidade antes que a nova possa ser adicionada. Isso exige chamar PFAccountManagementClientUnlinkSteamAccountAsync antes de vincular a conta atual da Steam. forceLink não resolve esse cenário.
  • Se a conta atual da Steam estiver vinculada a uma entidade diferente, chamar PFAccountManagementClientLinkSteamAccountAsync retornará E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED. Avise que a vinculação moverá a identidade da Steam para longe da outra entidade e tente novamente com forceLink=true após o consentimento.

​

Ações de confirmação (com base na escolha do jogador)

• O jogador escolhe o progresso do XBOX/MSA:
  • Garanta que a entidade da entrada com XBOX seja obtida (execute PFAuthenticationLoginWithXUserAsync com createAccount=false, se ainda não tiver sido feito durante a detecção).
  • Se a entidade XBOX já tiver uma conta da Steam diferente vinculada, chame PFAccountManagementClientUnlinkSteamAccountAsync para removê-la primeiro.
  • Vincule a Steam atual à conta baseada no XBOX. Se a chamada retornar E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED (a Steam está em outra entidade), tente novamente com forceLink=true após o consentimento.
  • Faça login novamente com o usuário local da Steam (PFLocalUserLoginAsync(..., /*createAccount*/ false, ...)) para associar a entidade.
• O jogador escolhe o progresso da Steam:
  • Se ainda não existir uma conta do PlayFab para a Steam, crie/associe via PFLocalUserLoginAsync(..., /*createAccount*/ true, ...).
  • Adie o vínculo do XBOX; permita a jogabilidade imediatamente. Ofereça a vinculação novamente na próxima vez.

​

Observações

• Sempre busque e exiba contexto suficiente para embasar a decisão do jogador.
• Registre telemetria dos resultados da reconciliação para melhorar os prompts e os padrões ao longo do tempo.

​

Diagrama de fluxo da Estratégia 2

​

Confira também

• Visão geral do PlayFab Game Saves
• Início rápido do Game Saves
• Conflitos do Game Saves
• Expiração de token e novo login