XUser 跨平台支援

​

概觀

​

整合需求

​

XBOX 主機與 Windows 上的 Microsoft Store / Game Pass

​

Windows 上的其他市集

• 遊戲使用作業系統內建的服務和 UI。
• 安裝程式應執行 GamingRepair.exe，以確保已安裝 Gaming Runtime Service。

1. 在遊戲套件中包含此工具 – 它隨附於 GDK 中，位於 [GDK]\bin\GamingRepair.exe。
2. 新增自訂動作 – 在遊戲安裝之前執行此工具 (例如：start /wait “Installing Gaming Services” GamingRepair.exe scenarioExternal)。這會驗證、下載、安裝或修復任何缺少的 Gaming Runtime 元件。
3. 處理錯誤 – 檢查工具的結束代碼。如果失敗，請通知使用者並提供手動安裝指示。

​

平台差異與統一 API

• 在具有原生支援的平台上 (XBOX、Windows) - XUser 使用作業系統的內建服務進行驗證、UI 和認證儲存。遊戲呼叫 XUser API，系統會自動處理細節。
• 在不具原生支援的平台上 (Steam Deck 等) - XUser 公開相同的核心 API，但遊戲必須實作事件處理常式，以提供必要的 UI (例如顯示登入用的 QR 代碼) 和資料儲存。這讓遊戲能完全掌控驗證體驗。

​

新的跨平台功能

​

遠端連線驗證

​

單一工作階段強制執行 (SPoP)

​

跨裝置登入的遠端連線

​

運作方式

​

流程

1. 事件處理常式註冊 - 遊戲在開始登入之前，使用 XUserPlatformRemoteConnectSetEventHandlers(...) 註冊 Remote Connect 事件處理常式。遊戲會提供回呼來處理兩個主要事件：
   • 顯示事件 - 當 XUser 需要遊戲顯示一次性代碼或 QR 代碼時觸發。處理常式會呈現包含代碼和指示的對話方塊或重疊畫面 (例如：「掃描此 QR 代碼，或造訪 xbox.com/play 並輸入代碼 ABCD 以登入」)。
   • 關閉事件 - 當遠端登入程序完成或取消時觸發，通知遊戲隱藏或關閉代碼對話方塊。
2. 起始使用者登入 - 呼叫 XUserAddAsync 新增使用者時，如果尚未有本機使用者登入，XUser 系統可能會使用 Remote Connect 流程 (特別是在無周邊或協力廠商平台上)。
3. 顯示代碼 - XUser 叫用「顯示」回呼，提供驗證代碼或 URL。遊戲的 UI 處理常式 (例如 OnRemoteConnectShow) 會向使用者顯示 QR 代碼或代碼字串。
4. 使用者驗證 - 玩家使用手機或網頁瀏覽器，以提供的代碼登入，將其 XBOX 帳戶連結到目前的工作階段。
5. 完成 - 後端完成驗證後，XUser 會叫用「關閉」回呼，表示可以從畫面上移除代碼。此時，XUser 已取得使用者的 XBOX Live 權杖，並建立 XUserHandle。
6. 成功 - XUserAddAsync 工作成功傳回，使用者無需直接在裝置上輸入認證即可登入。

​

實作

XUserPlatformRemoteConnectEventHandlers remoteConnect = {};
remoteConnect.context = nullptr;
remoteConnect.show = &OnRemoteConnectShow;   // Display QR/code dialog
remoteConnect.close = &OnRemoteConnectClose; // Dismiss dialog

HRESULT hr = XUserPlatformRemoteConnectSetEventHandlers(nullptr, &remoteConnect);

​

使用者體驗考量

• 清楚的指示 - 顯示代碼時，清楚說明使用者需要執行的動作。
• 錯誤處理 - 如果使用者在遠端取消或發生錯誤，XUser 會使登入嘗試失敗。請在 XUserAddAsync 的一般完成回呼中處理此情況。
• 及時關閉 - 發生關閉事件時立即隱藏代碼，以避免使用者混淆。
• 視覺設計 - 確保 QR 代碼和指示在目標裝置上夠大且清晰可見。

​

單一工作階段強制執行 (SPoP)

​

運作方式

​

流程

1. 事件處理常式註冊 - 遊戲在開始登入之前，使用 XUserPlatformSpopPromptSetEventHandlers(...) 註冊 SPoP 提示事件處理常式。
2. 衝突偵測 - 呼叫 XUserAddAsync 新增使用者時，如果 XUser 偵測到同一位使用者已在同一款遊戲的其他地方處於使用中狀態，就會叫用 SPoP 處理常式。
3. 顯示提示 - 遊戲的處理常式會收到使用者的新式玩家代號和作業控制代碼。處理常式應顯示 UI 提示，例如：「[玩家代號] 已在另一部裝置上遊玩。您要改為在此遊玩 (這會從其他地方登出)，還是切換到其他帳戶？」並提供「在此遊玩」和「切換帳戶」等選項。
4. 使用者選擇 - 遊戲等待使用者做出選擇。在遊戲呼叫完成 API 之前，作業會保持擱置狀態。
5. 完成作業 - 根據使用者的選擇，遊戲以適當的結果呼叫 XUserPlatformSpopPromptComplete：
   • 在此遊玩 - XUserPlatformSpopOperationResult::SignInHere - 在此裝置上登入並終止遠端工作階段。
   • 切換帳戶 - XUserPlatformSpopOperationResult::SwitchAccount - 取消在此裝置上的登入，讓使用者選擇其他帳戶。
   • 取消 - XUserPlatformSpopOperationResult::Canceled - 中止登入嘗試。
6. 解決 - XUser 根據結果繼續進行。如果選擇了「在此遊玩」，遠端工作階段會被終止 (另一部裝置會收到登出事件)，使用者會在本機變成使用中狀態。如果選擇了「切換帳戶」，XUserAddAsync 會失敗，遊戲可以提示使用者選擇其他帳戶。

​

實作

HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);

// If user chose "Play here"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SignInHere);

// If user chose "Switch account"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SwitchAccount);

// If dialog was canceled
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::Canceled);

​

使用者體驗考量

• 清楚的訊息 - 顯示使用者的玩家代號，並清楚說明繼續將會使其從另一部裝置登出。
• 明顯的選項 - 讓「在此遊玩」和「切換帳戶」兩個選項都清楚可見且易於理解。
• 避免存檔衝突 - 強調這可避免遊戲存檔衝突和同時遊玩的問題。
• 平台特定行為 - 在 XBOX 和 Windows 上，作業系統會自動處理此情況，永遠不會叫用 SPoP 處理常式。在其他平台上，您的遊戲負責呈現此選擇。

​

另請參閱