PlayFab Game Saves 的帳戶連結策略

​

主要連結身分識別

1. 玩家在每個可能遊玩該遊戲的平台上都能使用
2. 受到現有 PlayFab 登入呼叫支援，例如 LoginWithXbox 或 LoginWithOpenIdConnect

​

平台原生身分識別

• Steam：Steam 帳戶和驗證票證 (ISteamUser::GetAuthTicketForWebApi)
• PC/主機上的 XBOX：MSA/XBOX XUserHandle 和 XSTS 權杖
• PlayStation：PSN Online ID / 帳戶
• Nintendo：Nintendo Service Account / 裝置識別碼

​

連結策略選項

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 登入會傳回只用來連結 Steam 的 entityHandle。
• 連結後，再次以 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 衝突
• 權杖到期和重新登入