> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用者身分識別與 XUser

> 使用者身分識別與 XUser

XBOX One 使用 `XUser` 物件來管理與遊戲互動之使用者的身分識別。每個 `XUser` 執行個體代表一位已登入遊戲的使用者。每位使用者都以 `XUserHandle` 表示。遊戲可以使用 `XUserHandle` 執行下列作業。

* 查詢 XBOX services 登入狀態。
* 擷取使用者的玩家代號。
* 擷取使用者的玩家圖片。
* 判斷使用者的年齡群組。
* 判斷允許參與即時通訊或參與多人遊戲工作階段的使用者具有哪些權限。
* 擷取已驗證的權杖。

## XUser 識別碼

與指定 `XUser` 相關聯的識別碼有兩種：本機識別碼和 XBOX services 識別碼 (XUID)。

「本機識別碼」是在遊戲工作階段內，於使用者的整個存留期間都會跟隨該使用者的識別碼。在遊戲衍生的任何處理序之間，或遊戲呼叫 `XLaunchNewGame` 時，請使用本機識別碼。但是，請勿使用<br />本機識別碼來跨遊戲工作階段識別使用者。

若要取得使用者的本機識別碼，請使用 `XUserGetLocalId` 函式。

「XBOX services 識別碼 (XUID)」是與 XBOX services 通訊或叫用遊戲可呼叫 UI (TCUI) 時必須使用的識別碼。若要取得使用者的 XUID，請使用 `XUserGetId` 函式。取得 XUID 可能需要使用者同意。如果需要此同意但未獲得授與，`XUserGetId` 會傳回 E\_GAMEUSER\_RESOLVE\_USER\_ISSUE\_REQUIRED。若要解決此問題並收集同意，遊戲接著應呼叫 `XUserResolveIssueWithUiAsync`。

## XUser 狀態

使用者可能處於下列三種狀態之一：已登入 XBOX services、正在登出 XBOX services，或已完全登出。遊戲可以使用 `XUserGetState` 函式查詢指定使用者的此狀態。遊戲也可以使用 `XUserRegisterForChangeEvent` 函式註冊變更通知。

請勿根據 `XUser` 狀態判斷網路連線能力。如果 `XUserState` 為 `SignedIn`，這表示使用者曾在某個時間點通過 XBOX services 驗證，可以將其視為作用中的使用者。但是，網路可能並未連線。

## 在遊戲中新增或移除使用者

與 XBOX One ERA 的模型不同，遊戲只能與遊戲透過呼叫 `XUserAddAsync` 函式所要求的使用者互動。例如，假設有兩位使用者登入主機：使用者 A 和使用者 B。

1. 有人啟動遊戲。在此案例中，由誰啟動並不重要。
2. 遊戲使用 `XUserRegisterForChangeEvent` 註冊使用者狀態變更。
3. 遊戲呼叫 `XUserAddAsync`，使用者 A 登入遊戲。
4. 遊戲現在有代表使用者 A 的 `XUserHandle`。
5. 使用者 B 從指南中選擇登出。
6. 遊戲不會收到任何登入變更事件。遊戲從來都不知道使用者 B 的存在。
7. 使用者 A 從指南中選擇登出。
8. 遊戲會收到一個變更事件，首先指出使用者 A 正在登出，最後再收到另一個事件，指出使用者 A 現在已登出。

雖然遊戲能夠將使用者新增到遊戲中，但只有少數幾種方式可以移除使用者，方法如下。

* 遊戲可以使用 `XUserCloseHandle` 函式關閉代表該使用者的所有控制代碼。
* 使用者使用指南從主機登出。
* 使用者登入其他裝置。

## 使用者類型

XBOX One 支援兩種類型的使用者：XBOX 玩家和來賓。

「XBOX 玩家」在系統上擁有完整的使用者功能。他們最初是透過在帳戶選擇器 (系統提供的使用者登入 UI) 中新增帳戶來建立。XBOX 玩家會一直保留在主機上，直到使用 \[設定] 應用程式明確移除為止。

「XBOX 來賓」在主機上只有單一工作階段。當他們在帳戶選擇器中選擇以來賓身分遊玩時便會建立，並由另一位已登入的 XBOX 玩家贊助。來賓會一直保留，直到其登出、贊助的 XBOX 玩家登出，或主機關機為止。

想要允許來賓的遊戲在呼叫 `XUserAddAsync` 時，必須指定 `AllowGuest` 選項。

## 新增使用者的模式<a id="pattern_for_adding" />

遊戲必須一律嘗試建立初始使用者。有兩種主要方式可以達成此目的。

#### 選項 1：在不顯示 UI 的情況下盡快判斷使用者

1. 使用 `AddDefaultUserSilently` 呼叫 `XUserAddAsync`。此函式會嘗試在不顯示任何 UI 的情況下，判斷是誰啟動了遊戲。
2. 對 `XUserAddAsync` 的呼叫可能會失敗並傳回 `E\_GAMEUSER\_NO\_DEFAULT\_USER`。如果發生這種情況，表示首次啟動遊戲時沒有任何人登入。若要建立初始使用者，遊戲需要在不使用 `AddDefaultUserSilently` 旗標的情況下呼叫 `XUserAddAsync`。與「無訊息」選項不同，此呼叫可確保所有同意問題都已完全解決，而且如果呼叫成功，使用者就已登入 XBOX services。遊戲可以為該使用者建立 XBOX 內容。

#### 選項 2：在可能顯示 UI 的情況下判斷使用者

使用 `AddDefaultUserAllowingUI` 呼叫 `XUserAddAsync`。與先前的選項 (使用「無訊息」) 一樣，此函式會嘗試判斷是誰啟動了遊戲。與先前選項不同的是，如果無法判斷預設使用者，它會顯示 UI 讓玩家登入或選取自己。如果 `XUserAddResult` 成功，遊戲就有一位已完全登入 XBOX services 的使用者，遊戲可以為該使用者建立 XBOX 內容。

如需示範這些步驟的範例程式碼，請參閱[操作說明：登入使用者的最佳做法](/zh-TW/build/core-features/common/user/xuser_howto_best_practice_signing_in)。

## 管理 XUserHandle

每個 `XUserHandle` 代表一位使用者。但是，可能會有多個這類控制代碼都代表同一位使用者。遊戲應使用下列基本模式。

1. 維護一個 `XUserHandle` 執行個體的集合，代表遊戲所關注的使用者集合。
2. 呼叫 `XUserRegisterForChangeEvent` 註冊 `XUser` 狀態變更。當您發現某位使用者正在登出時，請更新您的使用者集合。
3. 當您從 `XUserAddAsync` 取得新的 `XUserHandle` 時，請務必檢查它是否代表新的使用者。您可以使用 `XUserCompare` 直接比較控制代碼。您也可以使用呼叫 `XUserGetLocalId` 所取得的本機識別碼進行比較。
4. 如果您有多個代表同一位使用者的 `XUserHandle` 執行個體，請使用 `XUserCloseHandle` 移除多餘的執行個體。

「本機識別碼」是在遊戲工作階段內，於使用者的整個存留期間都會跟隨該使用者的識別碼。在遊戲衍生的任何處理序之間，或遊戲呼叫 `XLaunchNewGame` 時，請使用本機識別碼。但是，請勿使用本機識別碼來跨遊戲工作階段識別使用者。


## Related topics

- [GDK 名詞與縮寫詞彙表](/zh-TW/home/glossary.md)
- [XR-112 在初始啟用和繼續時建立使用者與控制器](/zh-TW/publishing/certification/xr/xr-112.md)
- [從 PC(非 Steam)移植](/zh-TW/paths/porting/from-pc.md)
- [從其他平台移植](/zh-TW/paths/porting/from-console.md)
- [在 Partner Center 設定你的組織](/zh-TW/home/onboarding-access/setup-organization.md)