授予玩家附加元件內容的存取權

許多遊戲在 Microsoft Store 和遊戲內商店中提供可購買的附加元件內容。權利和授權是兩套系統，可協助判斷是否應授予玩家遊戲內附加元件內容的存取權。您使用的方法取決於內容類型 (例如耐久性、消耗性或套件組合) 以及遊戲的設計。您可以從服務管理消耗性權利、使用用戶端取得耐久性授權，或結合使用權利和授權來控制遊戲內的內容存取。

​

權利

權利代表客戶存取和使用數位產品 (包括遊戲、訂閱和附加元件) 的權利。在 Microsoft Store 中進行的每次購買或兌換，都會產生一或多個由 Microsoft 收藏服務追蹤的權利。如需適用於權利之產品類型的詳細資訊，請參閱選擇適當的產品類型。 產品權利可以透過玩家直接購買產品、購買滿足條件的產品 (例如套件組合或訂閱)，或來自其他使用者的共用權利來授予。權利支援多種狀態：使用中、非使用中、已過期和已撤銷。 遊戲用戶端和服務都可以查詢玩家的權利，但結果可能不同：

• 用戶端 API 只能傳回處於使用中狀態的權利，但可以傳回所有權利類型 (直接、共用、滿足)。不過，用戶端看不到權利的類型。
• 服務 API 可以傳回任何狀態的權利，但由於缺少裝置內容，無法傳回共用權利。不過，它們可以區分直接權利和滿足權利。

​

權利共用與離線可用性

• 當擁有產品的帳戶將目前裝置指定為其離線裝置時 (在主機上使用 Home XBOX，或在 PC 上使用 Offline permissions)，就會與裝置上的其他帳戶共用其非消耗性權利。
• 消耗性權利是與購買帳戶綁定的直接權利，無法與裝置上的其他帳戶共用。
• 所有權利查詢都需要線上連線。請勿在離線時使用權利來判斷玩家的存取權限，請改用授權。

​

遊戲用戶端的權利使用方式

每當用戶端傳送目錄要求時，都會對收藏服務傳送對應的呼叫，以填入每個傳回之 XStoreProduct 的 IsInUserCollection 屬性。如果 IsInUserCollection 為 true，表示玩家有權使用該產品。在決定哪些產品要在遊戲內商店中顯示為可購買或玩家已「擁有」時，請使用此值。 您可以透過下列方法擷取附加元件內容的 XStoreProduct 詳細資料：

• XStoreQueryAssociatedProductsAsync / Result - 只傳回可購買的產品。結果不包含已隱藏、僅能在套件組合中取得，或在 Microsoft Store 中已無法購買的產品。
• XStoreQueryProductsAsync / Result - 用於查詢特定產品。使用此函式檢查單一產品或產品子集的權利變更。

若要向收藏服務查詢所有使用中的權利，包括在 Microsoft Store 中已隱藏或已無法購買的產品，請呼叫：

• XStoreQueryEntitledProductsAsync / Result

建議您在遊戲重新取得焦點 (PC) 或從受限狀態返回 (主機) 時檢查權利變更，因為玩家可能會在離開遊戲期間取得新內容。如果附加元件內容可在外部商店 (Microsoft Store、XBOX App、xbox.com) 購買，則購買可能隨時在用戶端無法偵測的另一部裝置上發生。 請在遊戲中的策略性時間點檢查新權利，例如玩家造訪商店或物品欄功能表時。或者，您的遊戲可以偶爾輪詢更新，以縮短玩家購買產品到內容在遊戲中可用之間的延遲。 如需從用戶端查詢產品和權利的詳細資訊，請參閱基本 Store 作業。

​

遊戲服務的權利使用方式

使用遊戲服務時，可使用更進階的選項來查詢和管理權利。以下是一小部分可行的功能：

• 查詢使用者在整個發行者目錄中的權利。
• 區分直接權利和滿足權利，以更了解玩家如何取得內容。
• 查詢開始日期在未來的非使用中權利，以偵測仍處於預購狀態的購買。
• 管理健全的跨平台消耗性產品生態系統 (請參閱以消耗性產品為基礎的生態系統)。
• 使用 Clawback 服務偵測產品何時被退款 (請參閱從您的服務管理退款與退單)。
• 偵測 XBOX Game Pass 訂閱狀態，以在遊戲中為訂閱者提供福利 (請參閱從您的服務偵測 XBOX Game Pass 訂閱存取權)。

如需服務對服務功能的詳細資訊，請參閱從您的服務管理產品。

​

權利考量

• 當您在 PC 上的開發人員沙箱中作業時，用戶端會代表登入 XBOX App 的帳戶進行所有權利查詢。
• 當您在 PC 上的 RETAIL 中作業時，用戶端會代表登入 Microsoft Store 的帳戶進行所有權利查詢。當登入遊戲的帳戶與登入 Microsoft Store 的帳戶不相符時，可能會發生帳戶不相符的情況 (如需詳細資料，請參閱處理不相符的 Store 帳戶)。

如需權利常見問題的疑難排解，請參閱XStore 開發疑難排解。

​

授權

授權是一種數位金鑰，用來確認使用者在裝置上存取內容的權利。使用者必須有權使用該產品，或插入包含該產品的光碟 (遊戲和含套件的耐久性產品)，才能取得授權。 使用耐久性產品 (含或不含套件) 時，請使用授權來滿足共用、並行和離線可用性方面的預期 (請參閱遊戲的產品共用模型)。 授權會受到裝置限制和並行檢查的約束，這取決於遊戲使用的授權模型 (請參閱開放式與限制性授權。即使玩家擁有產品的使用中權利，也可能無法取得可在裝置上使用的有效授權。

​

授權共用與離線可用性

當下列一或多個條件成立時，就會在裝置上發生授權共用：

• 遊戲在擁有者帳戶已登入且已建立線上連線時取得授權。
• 遊戲為設定為離線裝置 (主機上的 Home XBOX 或 PC 上的 Offline permissions) 的擁有者帳戶取得離線授權。在此案例中，擁有帳戶不需要登入裝置，即可與其他帳戶共用其授權。
• 玩家插入包含 DLC (含套件的耐久性產品) 的光碟，且 DLC 已安裝在裝置上。

當下列一或多個條件成立時，授權可在離線時使用：

• 擁有產品的帳戶將目前裝置指定為其「離線」裝置 (在主機上使用 Home XBOX，或在 PC 上使用 Offline permissions)。啟用離線指定後，遊戲必須在線上時取得耐久性產品的授權。下次啟動遊戲時，就會取得可離線使用的授權。
• 玩家插入包含 DLC (含套件的耐久性產品) 的光碟，且 DLC 已安裝在裝置上。

​

遊戲用戶端的授權使用方式

您可以使用下列流程為耐久性產品 (含或不含套件) 授權：

• XStoreCanAcquireLicenseForStoreIdAsync / Result 會在不叫用並行檢查的情況下預覽授權。如果 XStoreCanLicenseStatus 為 Licensable，遊戲即可嘗試取得耐久性授權。此預覽檢查需要線上連線。
• 如果裝置上沒有授權或目前的授權已過期，XStoreAcquireLicenseForDurablesAsync / Result 會呼叫授權服務來取得授權。當裝置上已有產品的使用中授權，或在離線時呼叫此 API 時，會傳回快取的授權。如果傳回快取的授權，它對目前的玩家可能無效。
• 在遊戲中解除鎖定內容之前，請一律呼叫 XStoreIsLicenseValid 檢查授權是否有效。
• 如果您取得有效的授權，請使用 XStoreRegisterPackageLicenseLost 接聽授權遺失事件。如果授權遺失，請嘗試重新取得授權。如果無法重新取得授權，請決定何時或是否要封鎖玩家對內容的存取 (取決於遊戲的設計)。
• 處理授權遺失事件後，請呼叫 XStoreUnregisterPackageLicenseLost，並呼叫 XStoreCloseLicenseHandle 釋放舊的授權控制代碼。

如需如何使用 XStoreAcquireLicenseForDurablesAsync 的範例，請參閱如何使用不含套件的耐久性產品。 含套件的耐久性產品 (DLC) 可以作為光碟上遊戲套件組合的一部分。使用者必須插入光碟並安裝 DLC，遊戲才能取得授權。如果光碟中包含 DLC，或遊戲使用 XPackage API 列舉已安裝的套件，建議您使用每個授權 API 的 *ForPackage 變體：XStoreCanAcquireLicenseForPackageAsync / Result 和 XStoreAcquireLicenseForPackageAsync / Result。 如需列舉已安裝套件並為 DLC 授權的範例，請參閱管理可下載內容 (DLC) 並授權。

​

遊戲服務的授權使用方式

授權與裝置綁定，無法從遊戲服務查詢。不過，用戶端可以呼叫 XStoreQueryLicenseTokenAsync / Result，以使用遊戲服務提供額外的驗證。如需詳細資訊，請參閱使用授權權杖。

​

授權考量

• 從購買完成到可以取得新授權之間可能會有延遲。請檢查使用者權利的變更，並在新增耐久性產品的新權利後取得授權。
• 部署側載套件時，會自動為含套件的耐久性產品授予測試授權。若要測試含套件之耐久性產品的授權案例，請改用授權覆寫或從 Store 安裝的套件。如需詳細資訊，請參閱啟用授權測試。
• 當遊戲取得耐久性產品授權時，授權會快取在裝置上。在系統觸發授權重新整理之前，都會從快取中提取授權 (沒有 API 可以強制重新整理)。重複呼叫 XStoreAcquireLicense* 會檢查裝置快取，而不是服務。
• 授權遺失回呼可協助偵測系統是否錯誤地將屬於另一個帳戶的快取授權傳回給目前的玩家。在這種情況下，授權遺失事件會立即觸發，如果再次呼叫 XStoreAcquireLicense*，就會提供新的授權。
• 授權共用和快取可能會讓測試機器處於不乾淨的狀態。如需詳細資訊，請參閱XStore 開發疑難排解。

​

範例資源

如需示範如何查詢玩家權利和取得耐久性授權的範例程式碼，請參閱下列資源：

• InGameStore 範例 (GitHub)：示範 XStore 功能的 C++ 範例，包括產品擷取、購買、權利和耐久性產品授權。
• DownloadableContent 範例 (GitHub)：示範 XStore 和 XPackage 功能的 C++ 範例，包括列舉含套件的耐久性產品並為其授權。
• UnityInGameStore 範例 (GitHub)：使用 Unity 遊戲引擎和 ‘Microsoft GDK API package 示範 XStore 功能的 C# 範例。

​

參考 API 文件

• XStore (API 內容)
  • 函式
    • XStoreQueryAssociatedProductsAsync
    • Result
    • XStoreQueryProductsAsync
    • Result
    • XStoreQueryEntitledProductsAsync
    • Result
    • XStoreCanAcquireLicenseForStoreIdAsync
    • Result
    • XStoreAcquireLicenseForDurablesAsync
    • Result
    • XStoreIsLicenseValid
    • XStoreRegisterPackageLicenseLost
    • XStoreUnregisterPackageLicenseLost
    • XStoreCloseLicenseHandle
    • XStoreCanAcquireLicenseForPackageAsync
    • Result
    • XStoreAcquireLicenseForPackageAsync
    • Result
    • XStoreQueryLicenseTokenAsync
    • Result
  • 結構
    • XStoreProduct
• XPackage (API 內容)

​

另請參閱

商務概觀
XStore API 參考