PlayFab Game Saves 的帐户关联策略

​

主关联标识

1. 在玩家可能玩该游戏的每个平台上均可供玩家使用
2. 受现有 PlayFab Login 调用支持，例如 LoginWithXbox 或 LoginWithOpenIdConnect

​

平台原生标识

• Steam：Steam 帐户和身份验证票证 (ISteamUser::GetAuthTicketForWebApi)
• PC/主机上的 XBOX：MSA/XBOX XUserHandle 和 XSTS 令牌
• PlayStation：PSN 在线 ID/帐户
• Nintendo：Nintendo 服务帐户/设备 ID

​

关联策略选项

1. 所有玩家在游戏之前必须将其平台原生标识与你的主关联标识进行关联。
2. 平台原生标识与主关联标识之间的关联是可选的，但强烈建议在游戏之前进行关联。

​

期望状态

​

LocalUser 与登录

​

策略 1 - 必需的主标识关联

​

概要

• 玩家必须先使用跨平台标识 (XBOX/MSA) 登录，然后才能游戏。
• 从平台帐户 (Steam) 创建本地玩家，但在 XBOX/MSA 登录完成之前暂停在线游戏。
• XBOX/MSA 登录后，将平台帐户关联到跨平台帐户。
• 刷新本地平台配置文件，使其连接到跨平台帐户。
• 以后的启动将无缝进行：由于关联已建立，玩家可以直接开始游戏。

​

详细演练

• 调用 PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, customContext, outLocalUserHandle)。
• 结果：PFLocalUserHandle；尚未进行身份验证。

• 调用 PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ false, async)。
• 完成时，如果 PFLocalUserLoginGetResult 失败并返回 E_PF_ACCOUNT_NOT_FOUND，则触发 XBOX 登录以引导创建帐户。
• 如果 PFLocalUserLoginGetResult 成功，则说明我们已有处于期望状态的帐户并且已联机。工作流完成。

• 构建 PFAuthenticationLoginWithXUserRequest：
  • 设置 createAccount=true，以便在需要时创建 PlayFab 帐户。
  • 提供 PC 上已登录 XBOX 用户的 XUserHandle。
• 调用 PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, request, async)。
• 使用 PFAuthenticationLoginWithXUserGetResultSize(...) 和 PFAuthenticationLoginWithXUserGetResult(...) 完成操作以获取 PFEntityHandle。
• 注意：如果 LoginWithXUser 变体不可用，请使用 PFAuthenticationLoginWithXbox。这需要你自行从 XUserHandle 中提取 XSTS 令牌。

• 使用当前 Steam 身份验证票证(来自 ISteamUser::GetAuthTicketForWebApi 或集成中的等效函数；请在代码中确认确切的函数名称)构建客户端关联请求。
• 调用 PFAccountManagementClientLinkSteamAccountAsync(entityHandle, linkRequest, async)。
• 注意：“LinkSteamAccount” 位于 Account Management 下，而不是 Authentication 下。
• 成功后，玩家的 Steam 标识将关联到 XBOX 支持的 PlayFab 帐户。

• 再次调用 PFLocalUserLoginAsync(steamLocalUserHandle, /*createAccount*/ false, async)。
• PFLocalUserLoginGetResult 现在会成功；生成的 PFEntityHandle 绑定到 Steam 本地用户。

• Game Save 和其他在线 API 使用经过身份验证的 PFEntityHandle。
• 由于所有关联均已就绪，后续启动游戏时可以直接开始游戏。

• PFLocalUserCreateHandleWithSteamUser 本身不会登录，但尝试调用 PFGameSaveFilesAddUserWithUiAsync 会导致登录尝试。请确保在该调用之前已完成帐户关联流程。

​

关联冲突处理

• XBOX 登录后，调用 PFAccountManagementClientGetAccountInfoAsync(xboxEntity, getInfoRequest, async) 以获取帐户信息并检查已关联的标识。
• 如果实体已关联了另一个 Steam 帐户：
  • 警告玩家继续操作会从此实体中删除旧的 Steam 关联。征得同意。
  • 调用 PFAccountManagementClientUnlinkSteamAccountAsync(xboxEntity, unlinkRequest, async) 删除现有的 Steam 关联。
  • 然后使用当前 Steam 票证调用 PFAccountManagementClientLinkSteamAccountAsync。
• 如果关联调用返回 E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED(该 Steam 帐户属于另一个实体)：
  • 警告玩家此 Steam 帐户已与另一个 PlayFab 帐户关联，在此处关联会删除该关联。
  • 征得同意后使用 forceLink=true 重试。

​

示例 C++ 流程(Steam 优先门控、XBOX 引导、关联 Steam、再次使用 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));

• 使用 E_PF_ACCOUNT_NOT_FOUND 来决定是否走 XBOX 引导路径；单独处理其他错误。
• 继续使用 Steam PFLocalUserHandle；特定于提供程序的 XBOX 登录返回的 entityHandle 仅用于关联 Steam。
• 关联后，再次使用 Steam 登录，以将实体绑定到 LocalUser。
• 确保获取新的 Steam 票证用于关联。
• 不再需要时关闭句柄(PFLocalUserCloseHandle、PFEntityCloseHandle)。

​

策略 2 - 可选的主标识关联

​

概要

• 使用平台帐户 (Steam) 创建本地玩家，并尝试在不创建新帐户的情况下进行在线游戏。
• 如果在线可用，则继续；如果不可用，则提供以下选择：
  • 使用跨平台标识 (XBOX/MSA) 登录以创建统一帐户，或者
  • 立即创建仅限平台的帐户并马上开始游戏。
• 通过说明好处和风险，鼓励尽早关联到 XBOX/MSA。
• 当玩家选择关联时：
  • 如果直接关联成功，则使用统一帐户继续游戏。
  • 如果 XBOX/MSA 帐户在其他地方已有进度，则暂停并询问要保留哪个进度(协调)：
    • 保留 XBOX/MSA 进度并附加当前平台帐户。
    • 保留当前平台进度并推迟关联。
• 关联后，刷新本地平台配置文件，使其连接到统一帐户。
• 以后的启动将无缝进行：玩家可以直接开始游戏(假设未推迟关联)。

​

详细演练

• 调用 PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, customContext, outLocalUserHandle)。
• 结果：PFLocalUserHandle；尚未进行身份验证。

• 调用 PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ false, async)。
• 完成时：
  • 如果 PFLocalUserLoginGetResult 成功，则使用生成的 PFEntityHandle 并继续联机。
    • 检查 Steam 支持的帐户是否已关联到 XBOX/MSA。调用 PFAccountManagementClientGetAccountInfoAsync(entityHandle, getInfoRequest, async) 并检查已关联的标识。如果未关联，则提示玩家使用下面的流程关联 XBOX(非阻塞)，以便将来的跨平台进度能够无缝工作。
  • 如果 PFLocalUserLoginGetResult 失败并返回 E_PF_ACCOUNT_NOT_FOUND，则玩家将保持离线状态，直到创建帐户。提供两个选择：
    • 立即创建 XBOX 支持的 PlayFab 帐户：使用 XBOX/MSA 登录(例如 PFAuthenticationLoginWithXUserAsync)。
    • 立即使用 Steam 登录并开始游戏：调用 PFLocalUserLoginAsync(localUserHandle, /*createAccount*/ true, async) 创建绑定到本地句柄的 Steam 支持的 PlayFab 帐户；成功后，使用生成的 PFEntityHandle 立即联机。
  • 对于其他错误，请妥善处理(重试/退避)。

• 展示关联的好处(跨平台进度、权利可移植性)。
• 提供 XBOX/MSA 登录。

• 如果玩家稍后发起 XBOX 关联(他们已从当前会话获得 Steam 支持的 PFEntityHandle)：
  • 不要创建新的 XBOX 支持的帐户。
  • 通过调用相应的关联 API(例如 PFAccountManagementClientLinkXboxAccountAsync(currentSteamEntity, linkRequest, async))，尝试将 XBOX 标识直接关联到当前 Steam 支持的帐户。
  • 如果关联成功，则 XBOX/MSA 标识现已关联；继续正常操作。
  • 如果关联因预先存在的关联/冲突错误而失败(XBOX 标识已在其他位置关联)，则进入帐户协调模式。立即使用 createAccount=false 执行 XBOX/MSA 登录(例如 PFAuthenticationLoginWithXUserAsync)以获取 XBOX 支持的 PFEntityHandle，然后在提示玩家之前获取配置文件元数据作为上下文。征得同意后，继续进行关联决策。
• 如果玩家没有 XBOX 的现有帐户(引导路径)：
  • 首先使用 PFAuthenticationLoginWithXUserAsync(或在 LoginWithXUser 不可用时使用 PFAuthenticationLoginWithXboxAsync)以 createAccount=false 尝试 XBOX/MSA 登录。
    • 如果登录成功：XBOX/MSA 帐户已有 PlayFab 帐户，并且可能已有进度。进入帐户协调模式以选择要保留的进度。
    • 如果登录失败并返回 E_PF_ACCOUNT_NOT_FOUND：通过使用 createAccount=true 再次登录来创建 PlayFab 帐户。
  • 使用 PFAuthenticationLoginWithXUserGetResultSize(...) 和 PFAuthenticationLoginWithXUserGetResult(...) 完成操作以获取 PFEntityHandle。

• 适用于刚刚创建全新 XBOX 支持的 PlayFab 帐户(没有现有 Steam 关联)的情况。
• 如果之前已进入帐户协调，则关联决策和任何所需的 forceLink 操作都在那里处理；跳过此步骤。
• 使用当前 Steam 身份验证票证(来自 ISteamUser::GetAuthTicketForWebApi 或你的集成)构建客户端关联请求。
• 使用 forceLink=false(默认值)调用 PFAccountManagementClientLinkSteamAccountAsync(entityHandle, linkRequest, async)。对于全新帐户，此操作预计会成功。
• 如果关联失败，请将其视为错误情况(意外冲突或身份验证失败)。向玩家显示错误，并考虑在重试之前提示他们重新登录。
• 成功后，玩家的 Steam 标识将关联到 XBOX 支持的 PlayFab 帐户。

• 再次调用 PFLocalUserLoginAsync(steamLocalUserHandle, /*createAccount*/ false, async)。
• PFLocalUserLoginGetResult 现在会成功；生成的 PFEntityHandle 绑定到 Steam 本地用户。

• Game Save 和其他在线 API 使用经过身份验证的 PFEntityHandle。
• 由于所有关联均已就绪，后续启动游戏时将能够直接开始游戏。

• 不要使用 XBOX/MSA 登录阻止初始游戏；应尽早提示，但允许玩家推迟。
• PFLocalUserCreateHandleWithSteamUser 本身不会登录。请确保在调用会触发登录的 API(如 PFGameSaveFilesAddUserWithUiAsync)之前完成关联流程。

​

帐户协调(XBOX/MSA 上已有进度)

​

检测阶段

• 可以通过两种途径进入协调：
  1. 检测到现有 XBOX/MSA 帐户：使用 createAccount=false 尝试 XBOX/MSA 登录。
     • 如果登录成功，则 XBOX/MSA 标识已有 PlayFab 帐户，并且可能已有进度，此时进入协调。
     • 如果登录失败并返回 E_PF_ACCOUNT_NOT_FOUND，则继续进行引导 (createAccount=true)。无需进入协调。
  2. 检测到延迟关联冲突：将 XBOX/MSA 关联到当前 Steam 支持的帐户时，关联因预先存在的关联/冲突错误而失败(XBOX 标识已与另一个 Steam 标识关联)。
     • 立即使用 createAccount=false 执行 XBOX/MSA 登录(例如 PFAuthenticationLoginWithXUserAsync)以获取 XBOX 支持的 PFEntityHandle。
     • 获取配置文件元数据(例如最近的进度、存档槽、时间戳)以展示上下文。
     • 进入协调以决定要保留哪个进度。

​

协调阶段

• 推荐最直接的选项：保留 XBOX/MSA(主关联标识)进度并放弃本地 Steam 进度。这样可以保留跨平台锚点，并避免复杂的合并。
• 玩家实际上有三种选择(游戏可以选择仅提供其中 1-2 种)：
  1. 保留 XBOX/MSA 进度(推荐)：继续将当前 Steam 帐户关联到现有的 XBOX 支持的 PlayFab 帐户。
  2. 保留当前 Steam 进度并取消关联：暂时继续使用 Steam 支持的帐户；不关联或覆盖 XBOX/MSA 数据。下次再次提供关联。
  3. 保留当前 Steam 进度并放弃 XBOX 进度：切换到 Steam 支持的帐户，并有意放弃 XBOX/MSA 进度。此途径需要明确的游戏设计考量，不应轻易尝试，尤其是当其他平台原生标识已附加到 XBOX 帐户时。本文档不涉及此方案的实现细节。
• 提交之前：
  • 为 XBOX 实体调用 PFAccountManagementClientGetAccountInfoAsync，以检查现有的提供程序关联并验证是否已存在 Steam 关联。
  • 如果该实体已关联另一个 Steam 帐户，请警告玩家，在添加新关联之前，会从该实体中删除此现有 Steam 关联。这需要在关联当前 Steam 帐户之前调用 PFAccountManagementClientUnlinkSteamAccountAsync。forceLink 无法解决此情况。
  • 如果当前 Steam 帐户已关联到另一个实体，则调用 PFAccountManagementClientLinkSteamAccountAsync 会返回 E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED。警告关联会将 Steam 标识从另一个实体移走，然后在征得同意后使用 forceLink=true 重试。

​

提交操作(基于玩家选择)

• 玩家选择 XBOX/MSA 进度：
  • 确保已获取 XBOX 登录实体(如果在检测期间尚未执行，则使用 createAccount=false 执行 PFAuthenticationLoginWithXUserAsync)。
  • 如果 XBOX 实体已关联另一个 Steam 帐户，请先调用 PFAccountManagementClientUnlinkSteamAccountAsync 将其删除。
  • 将当前 Steam 关联到 XBOX 支持的帐户。如果调用返回 E_PF_LINKED_ACCOUNT_ALREADY_CLAIMED(Steam 位于另一个实体上)，请在征得同意后使用 forceLink=true 重试。
  • 再次使用 Steam 本地用户登录 (PFLocalUserLoginAsync(..., /*createAccount*/ false, ...)) 以绑定实体。
• 玩家选择 Steam 进度：
  • 如果 Steam 尚无 PlayFab 帐户，则通过 PFLocalUserLoginAsync(..., /*createAccount*/ true, ...) 创建/绑定。
  • 推迟 XBOX 关联；允许立即开始游戏。下次再次提供关联。

​

注意

• 始终获取并显示足够的上下文，以便玩家做出决定。
• 记录协调结果的遥测数据，以便随着时间推移改进提示和默认设置。

​

策略 2 流程图

​

另请参阅

• PlayFab Game Saves 概述
• Game Saves 快速入门
• Game Saves 冲突
• 令牌过期和重新登录