Stratégies de liaison de comptes pour PlayFab Game Saves

Identité de liaison principale

La première exigence de toute stratégie de progression multiplateforme consiste à déterminer quelle identité de joueur sera commune à toutes les plateformes de jeu. Le joueur doit pouvoir se connecter avec cette identité sur n’importe quel appareil sur lequel le jeu est disponible. Pour un titre first-party, il s’agit souvent du compte Microsoft (MSA)/compte XBOX. Pour de nombreux éditeurs tiers, il s’agit probablement d’une identité d’éditeur exposée via une implémentation OpenID Connect. Les deux exigences de cette identité de joueur sont les suivantes :

Être disponible pour les joueurs sur toutes les plateformes sur lesquelles ils peuvent jouer au jeu
Être prise en charge par un appel de connexion PlayFab existant, tel que LoginWithXbox ou LoginWithOpenIdConnect

Au-delà de ces deux exigences, il est utile que l’identité prenne en charge une forme de mise en cache sur l’appareil et une connexion silencieuse lors des lancements suivants du jeu. Ce n’est pas une exigence stricte, mais cela peut réduire la complexité des flux de travail et/ou les frictions pour le joueur.

Identité native de la plateforme

Une identité native de la plateforme est le système de comptes fourni par la plateforme sur laquelle le joueur exécute le jeu. Par exemple :

Steam : compte Steam et ticket d’authentification (ISteamUser::GetAuthTicketForWebApi)
XBOX sur PC/console : XUserHandle MSA/XBOX et jeton XSTS
PlayStation : Online ID/compte PSN
Nintendo : compte de service Nintendo/ID d’appareil

Ces identités servent généralement à créer et à réutiliser un PFLocalUserHandle pour le joueur actif sur un appareil donné (par exemple, PFLocalUserCreateHandleWithSteamUser ou l’encapsulation d’un XUserHandle). Elles peuvent également servir à s’authentifier via les API de connexion PlayFab propres à chaque fournisseur (par exemple, LoginWithSteam, LoginWithXbox), le cas échéant. Dans les scénarios de progression multiplateforme, les identités natives de la plateforme sont liées à l’identité de liaison principale, afin que la progression et les droits suivent le joueur d’une plateforme à l’autre. Les flux de travail recommandés dans ce document utilisent l’identité native de la plateforme comme contexte d’utilisateur local et l’identité de liaison principale comme point d’ancrage multiplateforme.

Options de stratégie de liaison

Ce document examine deux stratégies apparentées :

Tous les joueurs sont obligés de lier leur identité native de la plateforme à votre identité de liaison principale avant de jouer.
La liaison entre l’identité native de la plateforme et l’identité de liaison principale est facultative, mais fortement encouragée avant de jouer.

La première stratégie est plus simple à implémenter et évite aux joueurs des décisions difficiles susceptibles d’entraîner des pertes de progression par la suite. Elle augmente toutefois les frictions au démarrage du jeu et peut susciter un sentiment négatif lorsque les joueurs ne voient pas suffisamment d’intérêt à l’exigence de liaison initiale. Elle est particulièrement inadaptée à de nombreux jeux free-to-play et mobiles, qui reposent sur des barrières d’entrée extrêmement faibles pour attirer le plus de joueurs possible. La deuxième stratégie améliore l’expérience initiale du joueur, au prix de conflits potentiels et de décisions difficiles par la suite, ainsi que d’une complexité de code accrue pour les développeurs. Les joueurs peuvent commencer sans aucune exigence de connexion supplémentaire. Ils peuvent même commencer entièrement hors connexion si le jeu le permet. Cette flexibilité peut toutefois poser problème plus tard, lorsqu’ils décident d’effectuer la liaison. Il est possible que l’identité à laquelle ils se lient comporte déjà une progression sur une autre plateforme. Dans ce cas, l’établissement de la liaison peut impliquer soit l’abandon d’une progression, soit une fusion complexe que le jeu devra gérer. Même si les jeux choisissent cette stratégie, ils sont encouragés à promouvoir la liaison le plus tôt possible, à en décrire les avantages et à avertir des risques potentiels de l’absence de liaison. En fin de compte, le choix entre ces stratégies doit être guidé par des considérations commerciales. Aucune n’est clairement supérieure à l’autre. Le marché montre clairement que le passage de l’option 2 à l’option 1 après le lancement suscite le mécontentement des joueurs. Il est donc important de faire le bon choix dès le départ et de concevoir le jeu en conséquence.

État souhaité

Quelle que soit la stratégie, l’objectif ultime est d’amener chaque joueur dans le même état : son identité de liaison principale doit être liée à l’identité native de la plateforme sur chaque appareil sur lequel il joue. Dans cet état, la progression est systématiquement associée à l’identité de liaison principale, et les identités natives de la plateforme peuvent également servir de substitut efficace à l’identité principale sur toutes les plateformes. Sur certaines plateformes, il est possible que l’identité de liaison principale soit l’identité native de la plateforme (jeux first-party exécutés sur XBOX). Dans ces cas, il devient trivial d’atteindre l’état souhaité. Ce document ne les examine pas en détail, car les conseils existants en matière de connexion et de liaison sont suffisants.

LocalUser et connexion

Il est important de distinguer deux concepts apparentés, mais distincts, du SDK PlayFab. Un appel LocalUserCreate construit un objet d’utilisateur local et renvoie un PFLocalUserHandle sans effectuer aucune authentification. Il identifie et met en cache l’utilisateur à l’aide d’un ID local propre à la plateforme ou persistant (par exemple, en encapsulant un XUserHandle), afin que vous puissiez réutiliser le même contexte local d’une opération et d’une instance de jeu à l’autre. Cette opération est purement locale : elle n’effectue aucune requête réseau, n’obtient pas de jeton d’entité et ne crée pas de compte PlayFab. À l’inverse, un appel Login authentifie l’utilisateur local auprès de PlayFab et établit une entité authentifiée, avec ses jetons et ses ID. L’appel Login effectue des requêtes réseau (comme /Client/LoginWithXbox) et respecte des indicateurs tels que createAccount ; une fois l’appel réussi, le résultat est mis en cache afin que les appels suivants puissent réutiliser l’état authentifié. En résumé, la création d’un utilisateur local met en place l’identité locale et la gestion des handles requises pour PlayFab Game Saves, tandis que la connexion est l’étape qui contacte PlayFab pour s’authentifier et activer les API nécessitant une entité.

Stratégie 1 : liaison obligatoire de l’identité principale

Pour illustrer cette stratégie, prenons l’exemple d’un jeu first-party XBOX distribué sur Steam. Le jeu utilise XBOX/MSA comme identité de liaison principale. Il exige que tous les joueurs se connectent à leur compte XBOX/MSA avant de jouer. Il utilise tout de même un LocalUserHandle basé sur l’identité Steam, mais bloque la connexion effective jusqu’à ce que le joueur ait créé et lié une identité XBOX. Lors des lancements suivants, il peut passer directement par l’identité Steam, puisque la liaison a été vérifiée.

Résumé général

Le joueur doit se connecter avec l’identité multiplateforme (XBOX/MSA) avant de jouer.
Créez un joueur local à partir du compte de plateforme (Steam), mais suspendez le jeu en ligne jusqu’à ce que la connexion XBOX/MSA soit terminée.
Après la connexion XBOX/MSA, liez le compte de plateforme au compte multiplateforme.
Actualisez le profil de plateforme local afin qu’il soit connecté au compte multiplateforme.
Les lancements suivants sont transparents : le joueur peut jouer directement, car la liaison est établie.

Procédure détaillée

Créer un handle d’utilisateur local Steam

Appelez PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, customContext, outLocalUserHandle).
Résultat : PFLocalUserHandle ; aucune authentification pour l’instant.

Tenter de passer en ligne

Appelez PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ false, async).
À la fin de l’opération, si PFLocalUserLoginGetResult échoue avec E_PF_ACCOUNT_NOT_FOUND, déclenchez la connexion XBOX pour initialiser le compte.
Si PFLocalUserLoginGetResult réussit, nous disposons déjà d’un compte dans l’état souhaité et il est en ligne. Le flux de travail est terminé.

Si votre titre exige que l’identité multiplateforme reste liée à l’utilisateur actuel (par exemple, si le jeu exige une connexion XBOX et s’attend à ce que la liaison XBOX de l’entité corresponde au compte XBOX actuellement connecté), une connexion de plateforme réussie ne suffit pas. Appelez PFAccountManagementClientGetAccountInfoAsync après la connexion pour vérifier que la liaison multiplateforme correspond à l’utilisateur actuel. Si ce n’est pas le cas, l’entité est peut-être associée à une identité multiplateforme obsolète : suivez les étapes Se connecter via XBOX et Lier Steam ci-dessous pour rétablir la correspondance.

Se connecter via XBOX

Construisez un PFAuthenticationLoginWithXUserRequest :
- Définissez createAccount=true pour créer le compte PlayFab si nécessaire.
- Fournissez le XUserHandle de votre utilisateur XBOX connecté sur le PC.
Appelez PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, request, async).
Terminez avec PFAuthenticationLoginWithXUserGetResultSize(...) et PFAuthenticationLoginWithXUserGetResult(...) pour obtenir PFEntityHandle.
Remarque : utilisez PFAuthenticationLoginWithXbox si la variante LoginWithXUser n’est pas disponible. Vous devez alors extraire vous-même le jeton XSTS du XUserHandle.

Lier Steam au compte PlayFab authentifié (adossé à XBOX)

Construisez une requête de liaison client avec le ticket d’authentification Steam actuel (obtenu via ISteamUser::GetAuthTicketForWebApi ou l’équivalent dans votre intégration ; vérifiez le nom exact de la fonction dans votre code).
Appelez PFAccountManagementClientLinkSteamAccountAsync(entityHandle, linkRequest, async).
Remarque : “LinkSteamAccount” se trouve sous Account Management, et non sous Authentication.
En cas de réussite, l’identité Steam du joueur est liée au compte PlayFab adossé à XBOX.

Associer l’utilisateur local Steam à une entité (après la liaison)

Appelez de nouveau PFLocalUserLoginAsync(steamLocalUserHandle, /*createAccount*/ false, async).
PFLocalUserLoginGetResult réussit désormais ; le PFEntityHandle obtenu est lié à l’utilisateur local Steam.

Fonctionnement normal par la suite

Game Save et les autres API en ligne utilisent le PFEntityHandle authentifié.
Les lancements suivants du jeu peuvent passer directement au jeu, car toutes les liaisons sont en place.

Remarques

PFLocalUserCreateHandleWithSteamUser n’effectue pas de connexion par lui-même, mais toute tentative d’appel de PFGameSaveFilesAddUserWithUiAsync entraîne une tentative de connexion. Assurez-vous d’avoir suivi le flux de liaison de comptes avant cet appel.

Gestion des conflits de liaison

Deux conflits distincts peuvent survenir lors de la liaison de Steam à l’entité adossée à XBOX. Chacun nécessite une solution différente :

Erreur	Signification	Solution
`E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED`	Le compte Steam actuel est lié à une entité PlayFab différente.	Appelez de nouveau `PFAccountManagementClientLinkSteamAccountAsync` avec `forceLink=true` (après consentement). Cela déplace la liaison Steam vers l’entité actuelle.
`E_PF_ACCOUNT_ALREADY_LINKED`	Un compte Steam différent est déjà lié à l’entité actuelle.	Appelez `PFAccountManagementClientUnlinkSteamAccountAsync` pour supprimer d’abord l’ancienne liaison Steam, puis appelez `PFAccountManagementClientLinkSteamAccountAsync` pour le nouveau compte Steam. `forceLink` ne résout pas cette erreur.

Flux recommandé :

Après la connexion XBOX, appelez PFAccountManagementClientGetAccountInfoAsync(xboxEntity, getInfoRequest, async) pour récupérer les informations du compte et inspecter les identités liées.
Si un compte Steam différent est déjà lié à l’entité :
- Avertissez le joueur que poursuivre supprimera l’ancienne association Steam de cette entité. Obtenez son consentement.
- Appelez PFAccountManagementClientUnlinkSteamAccountAsync(xboxEntity, unlinkRequest, async) pour supprimer la liaison Steam existante.
- Appelez ensuite PFAccountManagementClientLinkSteamAccountAsync avec le ticket Steam actuel.
Si l’appel de liaison renvoie E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED (le compte Steam appartient à une autre entité) :
- Avertissez le joueur que ce compte Steam est associé à un autre compte PlayFab et que le lier ici supprimera cette association.
- Réessayez avec forceLink=true après consentement.

Cela préserve l’autonomie du joueur et évite de remplacer des liaisons par inadvertance, tout en offrant un moyen clair de rapprocher les identités.

Exemple de flux C++ (contrôle Steam en premier, initialisation XBOX, liaison Steam, nouvelle connexion avec Steam) :

Cet exemple utilise des variables static XAsyncBlock pour simplifier la gestion de leur durée de vie. Le code de production doit allouer les blocs asynchrones de manière dynamique (par exemple, dans la structure de contexte) pour prendre en charge les appels simultanés ou réentrants.

// 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));

Notes d’implémentation :

Utilisez E_PF_ACCOUNT_NOT_FOUND pour décider de passer par l’initialisation XBOX ; gérez les autres erreurs séparément.
Continuez à utiliser le PFLocalUserHandle Steam ; la connexion XBOX propre au fournisseur renvoie un entityHandle utilisé uniquement pour lier Steam.
Après la liaison, reconnectez-vous avec Steam pour lier l’entité au LocalUser.
Veillez à obtenir un nouveau ticket Steam pour la liaison.
Fermez les handles lorsqu’ils ne sont plus nécessaires (PFLocalUserCloseHandle, PFEntityCloseHandle).

Stratégie 2 : liaison facultative de l’identité principale

Dans ce scénario, le jeu s’exécute sur Steam et utilise XBOX/MSA comme identité de liaison principale. Les joueurs peuvent commencer à jouer sans se connecter immédiatement à XBOX/MSA. Le jeu encourage une liaison précoce en présentant clairement ses avantages et en donnant des avertissements, mais le début de partie n’est pas bloqué.

Résumé général

Créez un joueur local à l’aide du compte de plateforme (Steam) et essayez de jouer en ligne sans créer de nouveau compte.
Si le jeu en ligne fonctionne, continuez ; sinon, proposez un choix :
- Se connecter avec l’identité multiplateforme (XBOX/MSA) pour créer un compte unifié, ou
- Créer dès maintenant un compte propre à la plateforme et commencer à jouer immédiatement.
Encouragez une liaison précoce à XBOX/MSA en expliquant les avantages et les risques.
Lorsque le joueur choisit d’effectuer la liaison :
- Si la liaison réussit directement, continuez à jouer avec un compte unifié.
- Si le compte XBOX/MSA comporte déjà une progression ailleurs, faites une pause et demandez quelle progression conserver (rapprochement) :
  - Conserver la progression XBOX/MSA et y rattacher le compte de plateforme actuel.
  - Conserver la progression de la plateforme actuelle et reporter la liaison.
Après la liaison, actualisez le profil de plateforme local afin qu’il soit connecté au compte unifié.
Les lancements suivants sont transparents : le joueur peut jouer directement (à condition que la liaison n’ait pas été reportée).

Procédure détaillée

Créer un handle d’utilisateur local Steam

Appelez PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, customContext, outLocalUserHandle).
Résultat : PFLocalUserHandle ; aucune authentification pour l’instant.

Tenter de passer en ligne (chemin Steam silencieux)

Appelez PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ false, async).
À la fin de l’opération :
- Si PFLocalUserLoginGetResult réussit, utilisez le PFEntityHandle obtenu et passez en ligne.
  - Vérifiez si le compte adossé à Steam est déjà lié à XBOX/MSA. Appelez PFAccountManagementClientGetAccountInfoAsync(entityHandle, getInfoRequest, async) et inspectez les identités liées. S’il n’est pas lié, invitez le joueur à lier XBOX à l’aide du flux ci-dessous (non bloquant), afin que la progression multiplateforme fonctionne ensuite de manière transparente.
- Si PFLocalUserLoginGetResult échoue avec E_PF_ACCOUNT_NOT_FOUND, le joueur reste hors connexion jusqu’à la création d’un compte. Proposez deux choix :
  - Créer dès maintenant un compte PlayFab adossé à XBOX : se connecter avec XBOX/MSA (par exemple, PFAuthenticationLoginWithXUserAsync).
  - Se connecter dès maintenant avec Steam et commencer à jouer : appelez PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ true, async) pour créer un compte PlayFab adossé à Steam et lié au handle local ; en cas de réussite, utilisez le PFEntityHandle obtenu pour passer immédiatement en ligne.
- Pour les autres erreurs, procédez à une gestion appropriée (nouvelle tentative/délai d’attente).

Inviter à lier XBOX (non bloquant)

Présentez les avantages de la liaison (progression multiplateforme, portabilité des droits).
Proposez la connexion XBOX/MSA.

Se connecter via XBOX (initialisation ou liaison tardive avec détection de rapprochement)

Si le joueur lance la liaison XBOX ultérieurement (il dispose déjà d’un PFEntityHandle adossé à Steam pour la session en cours) :
- Ne créez pas de nouveau compte adossé à XBOX.
- Tentez de lier directement l’identité XBOX au compte adossé à Steam actuel en appelant l’API de liaison appropriée (par exemple, PFAccountManagementClientLinkXboxAccountAsync(currentSteamEntity, linkRequest, async)).
- Si la liaison réussit, l’identité XBOX/MSA est désormais liée ; poursuivez le fonctionnement normal.
- Si la liaison échoue avec une erreur de liaison préexistante/de conflit (l’identité XBOX est déjà liée ailleurs), passez en mode Rapprochement de comptes. Effectuez immédiatement la connexion XBOX/MSA avec createAccount=false (par exemple, PFAuthenticationLoginWithXUserAsync) pour obtenir le PFEntityHandle adossé à XBOX, puis récupérez les métadonnées du profil pour fournir du contexte avant d’interroger le joueur. Après consentement, passez aux décisions de liaison.
Si le joueur n’a pas de compte existant pour XBOX (chemin d’initialisation) :
- Tentez d’abord la connexion XBOX/MSA avec createAccount=false à l’aide de PFAuthenticationLoginWithXUserAsync (ou de PFAuthenticationLoginWithXboxAsync lorsque LoginWithXUser n’est pas disponible).
  - Si la connexion réussit : le compte XBOX/MSA dispose déjà d’un compte PlayFab et probablement d’une progression existante. Passez en mode Rapprochement de comptes pour choisir la progression à conserver.
  - Si la connexion échoue avec E_PF_ACCOUNT_NOT_FOUND : créez le compte PlayFab en vous reconnectant avec createAccount=true.
- Terminez avec PFAuthenticationLoginWithXUserGetResultSize(...) et PFAuthenticationLoginWithXUserGetResult(...) pour obtenir PFEntityHandle.

Lier Steam au compte PlayFab authentifié (adossé à XBOX)

Applicable lorsque vous venez de créer un nouveau compte PlayFab adossé à XBOX (sans liaison Steam existante).
Si vous êtes passé précédemment en mode Rapprochement de comptes, les décisions de liaison et les éventuelles actions forceLink requises y sont gérées ; ignorez cette étape.
Construisez une requête de liaison client avec le ticket d’authentification Steam actuel (obtenu via ISteamUser::GetAuthTicketForWebApi ou votre intégration).
Appelez PFAccountManagementClientLinkSteamAccountAsync(entityHandle, linkRequest, async) avec forceLink=false (valeur par défaut). Cet appel devrait réussir pour un nouveau compte.
Si la liaison échoue, traitez-la comme une condition d’erreur (conflit inattendu ou échec d’authentification). Signalez l’erreur au joueur et envisagez de l’inviter à se reconnecter avant de réessayer.
En cas de réussite, l’identité Steam du joueur est liée au compte PlayFab adossé à XBOX.

Associer l’utilisateur local Steam à une entité (après la liaison)

Appelez de nouveau PFLocalUserLoginAsync(steamLocalUserHandle, /*createAccount*/ false, async).
PFLocalUserLoginGetResult réussit désormais ; le PFEntityHandle obtenu est lié à l’utilisateur local Steam.

Fonctionnement normal par la suite

Game Save et les autres API en ligne utilisent le PFEntityHandle authentifié.
Les lancements suivants du jeu pourront passer directement au jeu, car toutes les liaisons sont en place.

Remarques

Ne bloquez pas le début de partie par la connexion XBOX/MSA ; invitez le joueur tôt, mais permettez-lui de reporter.
PFLocalUserCreateHandleWithSteamUser n’effectue pas de connexion par lui-même. Assurez-vous que les flux de liaison sont terminés avant d’appeler des API qui déclenchent une connexion, comme PFGameSaveFilesAddUserWithUiAsync.

Rapprochement de comptes (progression existante sur XBOX/MSA)

Lorsqu’un joueur se connecte avec un compte XBOX/MSA qui comporte déjà une progression (par exemple, sur console ou sur une autre plateforme), vous devez éviter de créer aveuglément un nouveau compte ou de remplacer des liaisons existantes. Adoptez une approche prudente en deux phases pour détecter et rapprocher les comptes.

Formulation destinée aux joueurs : dans la documentation destinée aux développeurs, nous utilisons le terme « rapprochement ». Dans l’interface utilisateur destinée aux joueurs, préférez des termes plus clairs comme « Sélection du profil de jeu », « Choisir la progression » ou « Conserver la progression existante », afin de limiter la confusion et de souligner que le joueur sélectionne un profil avec lequel continuer (et non une fusion).

Phase de détection

Le rapprochement peut être déclenché par deux chemins :
1. Compte XBOX/MSA existant détecté : tentez la connexion XBOX/MSA avec createAccount=false.
  - Si la connexion réussit, l’identité XBOX/MSA dispose déjà d’un compte PlayFab et probablement d’une progression existante : passez en mode rapprochement.
  - Si la connexion échoue avec E_PF_ACCOUNT_NOT_FOUND, procédez à l’initialisation (createAccount=true). Il n’est pas nécessaire de passer en mode rapprochement.
2. Conflit de liaison tardive détecté : lors de la liaison de XBOX/MSA au compte adossé à Steam actuel, la liaison échoue avec une erreur de liaison préexistante/de conflit (l’identité XBOX est déjà liée à une autre identité Steam).
  - Effectuez immédiatement la connexion XBOX/MSA avec createAccount=false (par exemple, PFAuthenticationLoginWithXUserAsync) pour obtenir le PFEntityHandle adossé à XBOX.
  - Récupérez les métadonnées du profil (par exemple, la progression récente, les emplacements de sauvegarde, les horodatages) pour présenter le contexte.
  - Passez en mode rapprochement pour décider de la progression à conserver.

Phase de rapprochement

Recommandez l’option la plus simple : conserver la progression XBOX/MSA (identité de liaison principale) et abandonner la progression Steam locale. Cela préserve le point d’ancrage multiplateforme et évite des fusions complexes.
Les joueurs disposent en pratique de trois choix (les jeux peuvent choisir de n’en proposer qu’un ou deux) :
1. Conserver la progression XBOX/MSA (recommandé) : liez le compte Steam actuel au compte PlayFab adossé à XBOX existant.
2. Conserver la progression Steam actuelle et annuler la liaison : continuez pour l’instant avec le compte adossé à Steam ; ne liez pas et ne remplacez pas les données XBOX/MSA. Proposez de nouveau la liaison la prochaine fois.
3. Conserver la progression Steam actuelle et abandonner la progression XBOX : passez au compte adossé à Steam et abandonnez délibérément la progression XBOX/MSA. Ce chemin nécessite une réflexion explicite sur la conception du jeu et ne doit pas être emprunté à la légère, en particulier si d’autres identités natives de plateforme sont déjà rattachées au compte XBOX. Ce document ne couvre pas les détails d’implémentation de ce scénario.
Avant de valider :
- Appelez PFAccountManagementClientGetAccountInfoAsync pour l’entité XBOX afin d’inspecter les liaisons de fournisseurs existantes et de vérifier si une liaison Steam existe déjà.
- Si un compte Steam différent est lié à l’entité, avertissez le joueur que cette association Steam existante sera supprimée de l’entité avant que la nouvelle puisse être ajoutée. Cela nécessite d’appeler PFAccountManagementClientUnlinkSteamAccountAsync avant de lier le compte Steam actuel. forceLink ne résout pas ce scénario.
- Si le compte Steam actuel est lié à une entité différente, l’appel de PFAccountManagementClientLinkSteamAccountAsync renvoie E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED. Avertissez le joueur que la liaison retirera l’identité Steam de l’autre entité, puis réessayez avec forceLink=true après consentement.

Actions de validation (selon le choix du joueur)

Le joueur choisit la progression XBOX/MSA :
- Assurez-vous d’avoir obtenu l’entité de connexion XBOX (effectuez PFAuthenticationLoginWithXUserAsync avec createAccount=false si ce n’est pas déjà fait lors de la détection).
- Si un autre compte Steam est déjà lié à l’entité XBOX, appelez d’abord PFAccountManagementClientUnlinkSteamAccountAsync pour le supprimer.
- Liez le compte Steam actuel au compte adossé à XBOX. Si l’appel renvoie E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED (Steam est lié à une autre entité), réessayez avec forceLink=true après consentement.
- Reconnectez-vous avec l’utilisateur local Steam (PFLocalUserLoginAsync(..., /*createAccount*/ false, ...)) pour lier l’entité.
Le joueur choisit la progression Steam :
- S’il n’existe pas encore de compte PlayFab pour Steam, créez-le et liez-le via PFLocalUserLoginAsync(..., /*createAccount*/ true, ...).
- Reportez la liaison XBOX ; autorisez le jeu immédiatement. Proposez de nouveau la liaison la prochaine fois.

Remarques

Récupérez et affichez toujours suffisamment de contexte pour éclairer la décision du joueur.
Enregistrez des données de télémétrie sur les résultats des rapprochements afin d’améliorer progressivement les invites et les choix par défaut.

Diagramme de flux de la stratégie 2

Le diagramme suivant présente l’arbre de décision complet. Tous les chemins convergent vers un nœud terminal unique où le joueur atteint un état jouable.

XBOX Services

PlayFab

Stratégies de liaison de comptes pour PlayFab Game Saves

Identité de liaison principale

Identité native de la plateforme

Options de stratégie de liaison

État souhaité

LocalUser et connexion

Stratégie 1 : liaison obligatoire de l’identité principale

Résumé général

Procédure détaillée

Gestion des conflits de liaison

Exemple de flux C++ (contrôle Steam en premier, initialisation XBOX, liaison Steam, nouvelle connexion avec Steam) :

Stratégie 2 : liaison facultative de l’identité principale

Résumé général

Procédure détaillée

Rapprochement de comptes (progression existante sur XBOX/MSA)

Phase de détection

Phase de rapprochement

Actions de validation (selon le choix du joueur)

Remarques

Diagramme de flux de la stratégie 2

Voir aussi

​Identité de liaison principale

​Identité native de la plateforme

​Options de stratégie de liaison

​État souhaité

​LocalUser et connexion

​Stratégie 1 : liaison obligatoire de l’identité principale

​Résumé général

​Procédure détaillée

​Gestion des conflits de liaison

​Exemple de flux C++ (contrôle Steam en premier, initialisation XBOX, liaison Steam, nouvelle connexion avec Steam) :

​Stratégie 2 : liaison facultative de l’identité principale

​Résumé général

​Procédure détaillée

​Rapprochement de comptes (progression existante sur XBOX/MSA)

​Phase de détection

​Phase de rapprochement

​Actions de validation (selon le choix du joueur)

​Remarques

​Diagramme de flux de la stratégie 2

​Voir aussi

Identité de liaison principale

Identité native de la plateforme

Options de stratégie de liaison

État souhaité

LocalUser et connexion

Stratégie 1 : liaison obligatoire de l’identité principale

Résumé général

Procédure détaillée

Gestion des conflits de liaison

Exemple de flux C++ (contrôle Steam en premier, initialisation XBOX, liaison Steam, nouvelle connexion avec Steam) :

Stratégie 2 : liaison facultative de l’identité principale

Résumé général

Procédure détaillée

Rapprochement de comptes (progression existante sur XBOX/MSA)

Phase de détection

Phase de rapprochement

Actions de validation (selon le choix du joueur)

Remarques

Diagramme de flux de la stratégie 2

Voir aussi