Estrategias de vinculación de cuentas para PlayFab Game Saves

​

Identidad de vinculación principal

1. Estar disponible para los jugadores en todas las plataformas en las que puedan jugar al juego
2. Ser compatible con una llamada de inicio de sesión de PlayFab existente, como LoginWithXbox o LoginWithOpenIdConnect

​

Identidad nativa de la plataforma

• Steam: cuenta de Steam y vale de autenticación (ISteamUser::GetAuthTicketForWebApi)
• XBOX en PC/consola: XUserHandle de MSA/XBOX y token XSTS
• PlayStation: identificador en línea/cuenta de PSN
• Nintendo: cuenta de servicio de Nintendo/identificador de dispositivo

​

Opciones de estrategia de vinculación

1. Todos los jugadores están obligados a vincular su identidad nativa de la plataforma con su identidad de vinculación principal antes de jugar.
2. La vinculación entre la identidad nativa de la plataforma y la identidad de vinculación principal es opcional, pero muy recomendada antes de jugar.

​

Estado deseado

​

LocalUser frente a inicio de sesión

​

Estrategia 1: vinculación obligatoria de la identidad principal

​

Resumen de alto nivel

• El jugador debe iniciar sesión con la identidad multiplataforma (XBOX/MSA) antes de jugar.
• Cree un jugador local a partir de la cuenta de la plataforma (Steam), pero retenga el juego en línea hasta que se complete el inicio de sesión de XBOX/MSA.
• Después del inicio de sesión de XBOX/MSA, vincule la cuenta de la plataforma a la cuenta multiplataforma.
• Actualice el perfil local de la plataforma para que esté conectado a la cuenta multiplataforma.
• Los lanzamientos futuros son fluidos: el jugador puede ir directamente a jugar porque el vínculo está establecido.

​

Explicación detallada

• Llame a PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, customContext, outLocalUserHandle).
• Resultado: PFLocalUserHandle; todavía no hay autenticación.

• Llame a PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ false, async).
• Al finalizar, si PFLocalUserLoginGetResult falla con E_PF_ACCOUNT_NOT_FOUND, desencadene el inicio de sesión de XBOX para arrancar la cuenta.
• Si PFLocalUserLoginGetResult se realiza correctamente, ya tenemos una cuenta en el estado deseado y está en línea. Flujo de trabajo completado.

• Cree PFAuthenticationLoginWithXUserRequest:
  • Establezca createAccount=true para crear la cuenta de PlayFab si es necesario.
  • Proporcione el XUserHandle de su usuario de XBOX con sesión iniciada en el PC.
• Llame a PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, request, async).
• Complete con PFAuthenticationLoginWithXUserGetResultSize(...) y PFAuthenticationLoginWithXUserGetResult(...) para obtener PFEntityHandle.
• Nota: Use PFAuthenticationLoginWithXbox si la variante LoginWithXUser no está disponible. Esto requiere que extraiga usted mismo el token XSTS del XUserHandle.

• Cree una solicitud de vinculación de cliente con el vale de autenticación de Steam actual (de ISteamUser::GetAuthTicketForWebApi o su equivalente en su integración; confirme el nombre exacto de la función en su código).
• Llame a PFAccountManagementClientLinkSteamAccountAsync(entityHandle, linkRequest, async).
• Nota: “LinkSteamAccount” está en Account Management, no en Authentication.
• Después de que se realice correctamente, la identidad de Steam del jugador queda vinculada a la cuenta de PlayFab respaldada por XBOX.

• Llame de nuevo a PFLocalUserLoginAsync(steamLocalUserHandle, /*createAccount*/ false, async).
• PFLocalUserLoginGetResult ahora se realiza correctamente; el PFEntityHandle resultante queda enlazado al usuario local de Steam.

• Game Saves y otras API en línea usan el PFEntityHandle autenticado.
• Los lanzamientos posteriores del juego pueden ir directamente a jugar porque toda la vinculación está establecida.

• PFLocalUserCreateHandleWithSteamUser no inicia sesión por sí solo, pero intentar llamar a PFGameSaveFilesAddUserWithUiAsync genera un intento de inicio de sesión. Asegúrese de haber pasado por el flujo de vinculación de cuentas antes de esa llamada.

​

Control de conflictos de vinculación

• Después del inicio de sesión de XBOX, llame a PFAccountManagementClientGetAccountInfoAsync(xboxEntity, getInfoRequest, async) para obtener la información de la cuenta e inspeccionar las identidades vinculadas.
• Si la entidad ya tiene vinculada una cuenta de Steam diferente:
  • Advierta al jugador de que continuar quita la asociación antigua de Steam de esta entidad. Obtenga el consentimiento.
  • Llame a PFAccountManagementClientUnlinkSteamAccountAsync(xboxEntity, unlinkRequest, async) para quitar el vínculo de Steam existente.
  • Luego llame a PFAccountManagementClientLinkSteamAccountAsync con el vale de Steam actual.
• Si la llamada de vinculación devuelve E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED (la cuenta de Steam pertenece a otra entidad):
  • Advierta al jugador de que esta cuenta de Steam está asociada a una cuenta de PlayFab diferente y de que vincularla aquí elimina esa asociación.
  • Reintente con forceLink=true previo consentimiento.

​

Flujo de ejemplo en C++ (barrera inicial de Steam, arranque con XBOX, vinculación de Steam, nuevo inicio de sesión con 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 la vía de arranque de XBOX; controle los demás errores por separado.
• Siga usando el PFLocalUserHandle de Steam; el inicio de sesión de XBOX específico del proveedor devuelve un entityHandle que se usa solo para vincular Steam.
• Después de vincular, inicie sesión de nuevo con Steam para enlazar la entidad al LocalUser.
• Asegúrese de obtener un vale de Steam nuevo para la vinculación.
• Cierre los identificadores cuando ya no los necesite (PFLocalUserCloseHandle, PFEntityCloseHandle).

​

Estrategia 2: vinculación opcional de la identidad principal

​

Resumen de alto nivel

• Cree un jugador local con la cuenta de la plataforma (Steam) e intente jugar en línea sin crear una cuenta nueva.
• Si la conexión funciona, continúe; si no, ofrezca una elección:
  • Iniciar sesión con la identidad multiplataforma (XBOX/MSA) para crear una cuenta unificada, o
  • Crear ahora una cuenta solo de plataforma y empezar a jugar inmediatamente.
• Fomente la vinculación temprana con XBOX/MSA explicando las ventajas y los riesgos.
• Cuando el jugador elija vincular:
  • Si la vinculación se realiza correctamente de forma directa, siga jugando con una cuenta unificada.
  • Si la cuenta de XBOX/MSA ya tiene progreso en otro lugar, haga una pausa y pregunte qué progreso conservar (conciliación):
    • Conservar el progreso de XBOX/MSA y asociar la cuenta de la plataforma actual.
    • Conservar el progreso de la plataforma actual y aplazar la vinculación.
• Después de vincular, actualice el perfil local de la plataforma para que esté conectado a la cuenta unificada.
• Los lanzamientos futuros son fluidos: el jugador puede ir directamente a jugar (suponiendo que la vinculación no se haya aplazado).

​

Explicación detallada

• Llame a PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, customContext, outLocalUserHandle).
• Resultado: PFLocalUserHandle; todavía no hay autenticación.

• Llame a PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ false, async).
• Al finalizar:
  • Si PFLocalUserLoginGetResult se realiza correctamente, use el PFEntityHandle resultante y continúe en línea.
    • Compruebe si la cuenta respaldada por Steam ya está vinculada a XBOX/MSA. Llame a PFAccountManagementClientGetAccountInfoAsync(entityHandle, getInfoRequest, async) e inspeccione las identidades vinculadas. Si no está vinculada, pida al jugador que vincule XBOX con el flujo que se indica a continuación (sin bloqueo), para que la progresión cruzada futura funcione sin problemas.
  • Si PFLocalUserLoginGetResult falla con E_PF_ACCOUNT_NOT_FOUND, el jugador permanece sin conexión hasta que se cree una cuenta. Ofrezca dos opciones:
    • Crear ahora una cuenta de PlayFab respaldada por XBOX: inicie sesión con XBOX/MSA (por ejemplo, PFAuthenticationLoginWithXUserAsync).
    • Iniciar sesión con Steam ahora y empezar a jugar: llame a PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ true, async) para crear una cuenta de PlayFab respaldada por Steam enlazada al identificador local; si se realiza correctamente, use el PFEntityHandle resultante para continuar en línea inmediatamente.
  • Para otros errores, contrólelos correctamente (reintento/retroceso).

• Presente las ventajas de vincular (progresión cruzada, portabilidad de derechos).
• Ofrezca el inicio de sesión con XBOX/MSA.

• Si el jugador inicia la vinculación de XBOX más tarde (ya tiene un PFEntityHandle respaldado por Steam de la sesión actual):
  • No cree una cuenta respaldada por XBOX nueva.
  • Intente vincular la identidad de XBOX directamente a la cuenta respaldada por Steam actual llamando a la API de vinculación adecuada (por ejemplo, PFAccountManagementClientLinkXboxAccountAsync(currentSteamEntity, linkRequest, async)).
  • Si la vinculación se realiza correctamente, la identidad de XBOX/MSA queda vinculada; continúe con el funcionamiento normal.
  • Si la vinculación falla con un error de vínculo preexistente/conflicto (la identidad de XBOX ya está vinculada en otro lugar), entre en el modo de conciliación de cuentas. Realice inmediatamente el inicio de sesión de XBOX/MSA con createAccount=false (por ejemplo, PFAuthenticationLoginWithXUserAsync) para obtener el PFEntityHandle respaldado por XBOX y luego recupere los metadatos del perfil para dar contexto antes de preguntar al jugador. Tras el consentimiento, continúe con las decisiones de vinculación.
• Si el jugador no tiene una cuenta existente para XBOX (vía de arranque):
  • Primero intente el inicio de sesión de XBOX/MSA con createAccount=false mediante PFAuthenticationLoginWithXUserAsync (o PFAuthenticationLoginWithXboxAsync cuando LoginWithXUser no esté disponible).
    • Si el inicio de sesión se realiza correctamente: la cuenta de XBOX/MSA ya tiene una cuenta de PlayFab y probablemente un progreso existente. Entre en el modo de conciliación de cuentas para elegir qué progreso conservar.
    • Si el inicio de sesión falla con E_PF_ACCOUNT_NOT_FOUND: continúe con la creación de la cuenta de PlayFab iniciando sesión de nuevo con createAccount=true.
  • Complete con PFAuthenticationLoginWithXUserGetResultSize(...) y PFAuthenticationLoginWithXUserGetResult(...) para obtener PFEntityHandle.

• Aplicable cuando acaba de crear una cuenta de PlayFab respaldada por XBOX nueva (sin vínculos de Steam existentes).
• Si entró antes en la conciliación de cuentas, las decisiones de vinculación y las acciones de forceLink necesarias se controlan allí; omita este paso.
• Cree una solicitud de vinculación de cliente con el vale de autenticación de Steam actual (de ISteamUser::GetAuthTicketForWebApi o su integración).
• Llame a PFAccountManagementClientLinkSteamAccountAsync(entityHandle, linkRequest, async) con forceLink=false (valor predeterminado). Se espera que esto se realice correctamente para una cuenta nueva.
• Si la vinculación falla, trátela como una condición de error (conflicto inesperado o error de autenticación). Muestre un error al jugador y considere pedirle que inicie sesión de nuevo antes de reintentar.
• Después de que se realice correctamente, la identidad de Steam del jugador queda vinculada a la cuenta de PlayFab respaldada por XBOX.

• Llame de nuevo a PFLocalUserLoginAsync(steamLocalUserHandle, /*createAccount*/ false, async).
• PFLocalUserLoginGetResult ahora se realiza correctamente; el PFEntityHandle resultante queda enlazado al usuario local de Steam.

• Game Saves y otras API en línea usan el PFEntityHandle autenticado.
• Los lanzamientos posteriores del juego podrán ir directamente a jugar porque toda la vinculación está establecida.

• No bloquee el juego inicial con el inicio de sesión de XBOX/MSA; pídalo pronto, pero permita que los jugadores lo aplacen.
• PFLocalUserCreateHandleWithSteamUser no inicia sesión por sí solo. Asegúrese de que los flujos de vinculación se completan antes de llamar a las API que desencadenan el inicio de sesión, como PFGameSaveFilesAddUserWithUiAsync.

​

Conciliación de cuentas (progreso existente en XBOX/MSA)

​

Fase de detección

• Se puede entrar en la conciliación por dos vías:
  1. Se detecta una cuenta de XBOX/MSA existente: intente el inicio de sesión de XBOX/MSA con createAccount=false.
     • Si el inicio de sesión se realiza correctamente, la identidad de XBOX/MSA ya tiene una cuenta de PlayFab y probablemente un progreso existente: entre en la conciliación.
     • Si el inicio de sesión falla con E_PF_ACCOUNT_NOT_FOUND, continúe con el arranque (createAccount=true). No es necesario entrar en la conciliación.
  2. Se detecta un conflicto de vinculación tardía: al vincular XBOX/MSA a la cuenta respaldada por Steam actual, la vinculación falla con un error de vínculo preexistente/conflicto (la identidad de XBOX ya está vinculada a una identidad de Steam diferente).
     • Realice inmediatamente el inicio de sesión de XBOX/MSA con createAccount=false (por ejemplo, PFAuthenticationLoginWithXUserAsync) para obtener el PFEntityHandle respaldado por XBOX.
     • Recupere los metadatos del perfil (por ejemplo, progresión reciente, ranuras de guardado, marcas de tiempo) para presentar contexto.
     • Entre en la conciliación para decidir qué progreso conservar.

​

Fase de conciliación

• Recomiende la opción sencilla: conservar el progreso de XBOX/MSA (identidad de vinculación principal) y abandonar el progreso local de Steam. Esto preserva el ancla multiplataforma y evita fusiones complejas.
• Los jugadores tienen en la práctica tres opciones (los juegos pueden decidir ofrecer solo 1 o 2 de ellas):
  1. Conservar el progreso de XBOX/MSA (recomendado): proceda a vincular la cuenta de Steam actual a la cuenta de PlayFab respaldada por XBOX existente.
  2. Conservar el progreso de Steam actual y cancelar la vinculación: continúe con la cuenta respaldada por Steam por ahora; no vincule ni anule los datos de XBOX/MSA. Ofrezca la vinculación de nuevo la próxima vez.
  3. Conservar el progreso de Steam actual y abandonar el progreso de XBOX: cambie a la cuenta respaldada por Steam y descarte intencionadamente el progreso de XBOX/MSA. Esta vía requiere una consideración explícita de diseño del juego y no debe intentarse a la ligera, especialmente si otras identidades nativas de la plataforma ya están asociadas a la cuenta de XBOX. En este documento no cubrimos los detalles de implementación de este escenario.
• Antes de confirmar:
  • Llame a PFAccountManagementClientGetAccountInfoAsync para la entidad de XBOX a fin de inspeccionar los vínculos de proveedor existentes y comprobar si ya existe un vínculo de Steam.
  • Si la entidad tiene vinculada una cuenta de Steam diferente, advierta al jugador de que esta asociación de Steam existente se quita de la entidad antes de poder agregar la nueva. Esto requiere llamar a PFAccountManagementClientUnlinkSteamAccountAsync antes de vincular la cuenta de Steam actual. forceLink no resuelve este escenario.
  • Si la cuenta de Steam actual está vinculada a una entidad diferente, llamar a PFAccountManagementClientLinkSteamAccountAsync devuelve E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED. Advierta de que la vinculación aleja la identidad de Steam de la otra entidad y luego reintente con forceLink=true previo consentimiento.

​

Acciones de confirmación (según la elección del jugador)

• El jugador elige el progreso de XBOX/MSA:
  • Asegúrese de haber obtenido la entidad de inicio de sesión de XBOX (realice PFAuthenticationLoginWithXUserAsync con createAccount=false si no se hizo ya durante la detección).
  • Si la entidad de XBOX ya tiene vinculada una cuenta de Steam diferente, llame primero a PFAccountManagementClientUnlinkSteamAccountAsync para quitarla.
  • Vincule la cuenta de Steam actual a la cuenta respaldada por XBOX. Si la llamada devuelve E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED (Steam está en otra entidad), reintente con forceLink=true previo consentimiento.
  • Inicie sesión de nuevo con el usuario local de Steam (PFLocalUserLoginAsync(..., /*createAccount*/ false, ...)) para enlazar la entidad.
• El jugador elige el progreso de Steam:
  • Si todavía no existe una cuenta de PlayFab para Steam, créela/enlácela mediante PFLocalUserLoginAsync(..., /*createAccount*/ true, ...).
  • Aplace el vínculo de XBOX; permita jugar inmediatamente. Ofrezca la vinculación de nuevo la próxima vez.

​

Notas

• Recupere y muestre siempre contexto suficiente para informar la decisión del jugador.
• Registre telemetría de los resultados de la conciliación para mejorar los avisos y los valores predeterminados con el tiempo.

​

Diagrama de flujo de la estrategia 2

​

Consulte también

• Información general de PlayFab Game Saves
• Inicio rápido de Game Saves
• Conflictos de Game Saves
• Expiración de tokens y reinicio de sesión