> ## 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.

# 为玩家授予对附加内容的访问权限

> 通过权益与授权为玩家授予对 XBOX 附加内容的访问权限，包括耐用品、消耗品、捆绑包以及共享权益。

许多游戏在 Microsoft Store 和游戏内商店中提供可购买的附加内容。权益 (Entitlement) 和授权 (Licensing) 是两个系统，用于判断是否应向玩家授予对游戏内附加内容的访问权限。你使用的方法取决于内容类型（例如耐用品、消耗品或捆绑包）以及游戏的设计。你可以从服务端管理消耗品权益、通过客户端获取耐用品许可证，或将权益和授权两者结合使用以在游戏中控制对内容的访问。

## 权益

权益代表客户对数字产品（包括游戏、订阅和附加内容）的访问和使用权利。在 Microsoft Store 中进行的每次购买或兑换都会产生一个或多个由 Microsoft 的 collections 服务跟踪的权益。有关支持权益的产品类型的更多信息，请参阅[选择合适的产品类型](/publishing/xstore-commerce/xstore-choosing-product-type)。

产品权益可以通过玩家直接购买该产品、购买满足关系的产品（例如捆绑包或订阅），或来自另一位用户的共享权益来授予。权益支持多种状态：active、inactive、expired 和 revoked。

游戏客户端和服务都可以查询玩家的权益，但结果可能不同：

* 客户端 API 只能返回状态为 active 的权益，但可以返回所有权益类型（直接、共享、满足）。不过，客户端无法看到权益的类型。
* 服务端 API 可以返回任意状态的权益，但由于缺乏设备上下文，无法返回共享权益。不过，它们可以区分直接权益和满足权益。

### 权益共享与离线可用性

* 当拥有该产品的账号将当前设备指定为其离线设备时（在主机上使用 **Home XBOX**，或在 PC 上使用 **Offline permissions**），它会将其非消耗品权益与该设备上的其他账号共享。
* 消耗品权益是直接权益，与购买账号绑定，不能与设备上的其他账号共享。
* 所有权益查询都要求在线连接。请勿使用权益判断玩家在离线时的访问权。请改用[授权](#licensing)。

### 游戏客户端的权益用法

每当客户端发送目录请求时，都会向 collections 服务发送对应的调用，以填充每个返回的 [XStoreProduct](/reference/system/xstore/xstore_members) 的 `IsInUserCollection` 属性。如果 `IsInUserCollection` 为 true，则表示玩家有权使用该产品。在决定哪些产品在你的游戏内商店中显示为可购买或玩家已“拥有”时，请使用此值。

你可以通过以下方法获取附加内容的 XStoreProduct 详情：

* [XStoreQueryAssociatedProductsAsync](/reference/system/xstore/xstore_members) / [Result](/reference/system/xstore/xstore_members) - 仅返回可购买的产品。结果不包括在 Microsoft Store 中隐藏、仅在捆绑包中可用或已不再可购买的产品。
* [XStoreQueryProductsAsync](/reference/system/xstore/xstore_members) / [Result](/reference/system/xstore/xstore_members) - 用于查询特定产品。使用此函数检查单个产品或产品子集的权益变化。

若要查询 collections 服务以获取所有活跃权益，包括在 Microsoft Store 中隐藏或已不再可购买的产品，请调用：

* [XStoreQueryEntitledProductsAsync](/reference/system/xstore/xstore_members) / [Result](/reference/system/xstore/xstore_members)

我们建议在游戏重新获得焦点（PC）或从受限状态返回（主机）时检查权益变化，因为玩家可能在离开游戏期间获取了新内容。如果附加内容可在外部店面（Microsoft Store、XBOX 应用、xbox.com）购买，则购买可能随时在其他设备上发生，客户端无法检测到。

在游戏的关键点检查新权益，例如玩家访问商店或库存菜单时。或者你的游戏可以偶尔轮询更新，以减少玩家购买产品与内容在游戏中可用之间的延迟。

有关从客户端查询产品和权益的详细信息，请参阅[商店基本操作](/publishing/xstore-commerce/xstore-basic-operations)。

### 游戏服务的权益用法

使用游戏服务时，可以获得更高级的权益查询和管理选项。以下是可能功能的一小部分：

* 跨整个发行商目录查询用户的权益。
* 区分直接权益和满足权益，以更好地了解玩家如何获取内容。
* 查询将来开始日期的非活跃权益，以检测仍处于预购状态的购买。
* 管理强大的跨平台消耗品生态系统（请参阅[基于消耗品的生态系统](/publishing/xstore-commerce/xstore-consumables)）。
* 使用 Clawback 服务检测产品何时被退款（请参阅[从你的服务管理退款和拒付](/publishing/xstore-commerce/xstore-managing-refunds)）。
* 检测 XBOX Game Pass 订阅状态，以在游戏中为订阅者授予福利（请参阅[从你的服务检测 XBOX Game Pass 订阅访问](/publishing/xstore-commerce/xstore-detecting-game-pass)）。

有关服务到服务功能的更多信息，请参阅[从你的服务管理产品](/publishing/xstore-commerce/xstore-authenticating-service)。

### 权益注意事项

* 在 PC 的开发者沙盒中操作时，客户端会代表登录 XBOX 应用的账号进行所有权益查询。
* 在 PC 的 RETAIL 中操作时，客户端会代表登录 Microsoft Store 的账号进行所有权益查询。当登录游戏的账号与登录 Microsoft Store 的账号不匹配时，可能会出现账号不匹配的场景（详情请参阅[处理商店账号不匹配](/publishing/xstore-commerce/xstore-mismatched-accounts)）。

有关权益常见问题的故障排除，请参阅[排查 XStore 开发问题](/publishing/xstore-commerce/xstore-troubleshooting)。

## 授权

许可证是确认用户在设备上有权访问内容的数字密钥。在获取许可证之前，用户必须有权使用该产品或插入包含该产品的光盘（游戏和带包的耐用品）。

在处理耐用品（带包或不带包）时，使用授权满足在共享、并发和离线可用性方面的期望（请参阅[游戏的产品共享模式](/publishing/xstore-commerce/xstore-product-sharing)）。

许可证受设备限制和并发检查约束，这些约束依赖于游戏使用的许可证模型（请参阅[开放式与限制式授权](/publishing/xstore-commerce/xstore-open-restrictive-licensing)）。即使玩家对该产品有活跃的权益，也可能无法获取用于该设备的有效许可证。

### 许可证共享与离线可用性

在满足以下一项或多项条件时，设备上会发生许可证共享：

* 游戏在拥有者的账号登录且建立在线连接时获取了许可证。
* 游戏在拥有者的账号被指定为该设备的离线账号时（在主机上使用 **Home XBOX** 或在 PC 上使用 **Offline permissions**）获取了离线许可证。在这种情况下，拥有账号无需登录到设备即可与该设备上的其他账号共享其许可证。
* 玩家插入包含该 DLC（带包的耐用品）的光盘，并且该 DLC 已安装在设备上。

在满足以下一项或多项条件时，许可证可在离线时可用：

* 拥有该产品的账号将当前设备指定为其“离线”设备（在主机上使用 **Home XBOX** 或在 PC 上使用 **Offline permissions**）。启用离线指定后，游戏必须在联机时获取该耐用品产品的许可证。下次启动游戏时，它会获取具备离线能力的许可证。
* 玩家插入包含该 DLC（带包的耐用品）的光盘，并且该 DLC 已安装在设备上。

### 游戏客户端的许可证用法

可以使用以下流程为耐用品（带包或不带包）授权：

* [XStoreCanAcquireLicenseForStoreIdAsync](/reference/system/xstore/xstore_members) / [Result](/reference/system/xstore/xstore_members) 在不触发并发检查的情况下预览许可证。如果 [XStoreCanLicenseStatus](/reference/system/xstore/xstore_members) 为 `Licensable`，则游戏可以尝试获取耐用品许可证。此预览检查需要在线连接。
* [XStoreAcquireLicenseForDurablesAsync](/reference/system/xstore/xstore_members) / [Result](/reference/system/xstore/xstore_members) 在设备上没有许可证或当前许可证已过期时调用授权服务以获取许可证。当设备上已有该产品的活跃许可证或在离线时调用此 API 时，会返回缓存的许可证。如果返回的是缓存的许可证，它可能对当前玩家无效。
* 在游戏中解锁内容之前，始终调用 [XStoreIsLicenseValid](/reference/system/xstore/xstore_members) 检查许可证是否有效。
* 如果获取了有效许可证，请使用 [XStoreRegisterPackageLicenseLost](/reference/system/xstore/xstore_members) 监听许可证丢失事件。如果许可证丢失，请尝试重新获取许可证。如果无法重新获取许可证，请决定何时（或是否）阻止玩家对内容的访问（取决于游戏设计）。
* 在处理许可证丢失事件后，调用 [XStoreUnregisterPackageLicenseLost](/reference/system/xstore/xstore_members) 并通过调用 [XStoreCloseLicenseHandle](/reference/system/xstore/xstore_members) 释放旧的许可证句柄。

有关如何使用 XStoreAcquireLicenseForDurablesAsync 的示例，请参阅[如何使用无包的耐用品](/publishing/xstore-commerce/xstore-dwob)。

带包的耐用品 (DLC) 可以作为游戏光盘捆绑包的一部分包含在光盘上。用户必须插入光盘并安装 DLC，游戏才能获取许可证。如果 DLC 包含在光盘上，或者游戏使用 [XPackage](/reference/system/xstore/xstore_members) API 枚举已安装的包，我们建议使用每个授权 API 的 \*ForPackage 变体：[XStoreCanAcquireLicenseForPackageAsync](/reference/system/xstore/xstore_members) / [Result](/reference/system/xstore/xstore_members) 和 [XStoreAcquireLicenseForPackageAsync](/reference/system/xstore/xstore_members) / [Result](/reference/system/xstore/xstore_members)。

有关枚举已安装包并授权 DLC 的示例，请参阅[管理并授权可下载内容 (DLC)](/publishing/xstore-commerce/xstore-dlc)。

### 游戏服务的许可证用法

许可证与设备绑定，无法从游戏服务查询。不过，客户端可以调用 [XStoreQueryLicenseTokenAsync](/reference/system/xstore/xstore_members) / [Result](/reference/system/xstore/xstore_members) 通过游戏服务提供额外验证。有关更多信息，请参阅[使用许可证令牌](/publishing/xstore-commerce/xstore-license-tokens)。

### 授权注意事项

* 购买完成到可获取新许可证之间可能存在延迟。请检查用户[权益](#entitlements)的变化，并在为耐用品产品添加新权益后获取许可证。
* 部署侧载包时，会自动为带包的耐用品授予测试许可证。若要测试带包耐用品的授权场景，请改用许可证覆盖或从商店安装的包。有关更多信息，请参阅[启用授权测试](/publishing/xstore-commerce/xstore-licensing-setup)。
* 当游戏获取耐用品许可证时，该许可证会缓存在设备上。许可证会从缓存中拉取，直到系统触发许可证刷新（没有可强制刷新的 API）。对 XStoreAcquireLicense\* 的重复调用会检查设备缓存，而不是服务。
* 许可证丢失回调可以帮助检测系统是否错误地向当前玩家返回了属于另一个账号的缓存许可证。在这种情况下，许可证丢失事件会立即触发；如果再次调用 XStoreAcquireLicense\*，会提供全新的许可证。
* 许可证共享和缓存可能会让测试机器处于不干净的状态。有关更多信息，请参阅[排查 XStore 开发问题](/publishing/xstore-commerce/xstore-troubleshooting)。

## 示例资源

有关演示如何查询玩家权益和获取耐用品许可证的示例代码，请参阅以下资源：

* [InGameStore 示例 (GitHub)](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Live/InGameStore)：演示 XStore 功能的 C++ 示例，包括产品检索、购买、权益和耐用品授权。
* [DownloadableContent 示例 (GitHub)](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Live/DownloadableContent)：演示 XStore 和 XPackage 功能的 C++ 示例，包括枚举和授权已打包的耐用品。
* [UnityInGameStore 示例 (GitHub)](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Unity/Live/UnityInGameStore)：使用 Unity 游戏引擎和 “Microsoft GDK API package” 演示 XStore 功能的 C# 示例。

## 参考 API 文档

* [XStore（API 内容）](/reference/system/xstore/xstore_members)
  * 函数
    * [XStoreQueryAssociatedProductsAsync](/reference/system/xstore/xstore_members)
    * [Result](/reference/system/xstore/xstore_members)
    * [XStoreQueryProductsAsync](/reference/system/xstore/xstore_members)
    * [Result](/reference/system/xstore/xstore_members)
    * [XStoreQueryEntitledProductsAsync](/reference/system/xstore/xstore_members)
    * [Result](/reference/system/xstore/xstore_members)
    * [XStoreCanAcquireLicenseForStoreIdAsync](/reference/system/xstore/xstore_members)
    * [Result](/reference/system/xstore/xstore_members)
    * [XStoreAcquireLicenseForDurablesAsync](/reference/system/xstore/xstore_members)
    * [Result](/reference/system/xstore/xstore_members)
    * [XStoreIsLicenseValid](/reference/system/xstore/xstore_members)
    * [XStoreRegisterPackageLicenseLost](/reference/system/xstore/xstore_members)
    * [XStoreUnregisterPackageLicenseLost](/reference/system/xstore/xstore_members)
    * [XStoreCloseLicenseHandle](/reference/system/xstore/xstore_members)
    * [XStoreCanAcquireLicenseForPackageAsync](/reference/system/xstore/xstore_members)
    * [Result](/reference/system/xstore/xstore_members)
    * [XStoreAcquireLicenseForPackageAsync](/reference/system/xstore/xstore_members)
    * [Result](/reference/system/xstore/xstore_members)
    * [XStoreQueryLicenseTokenAsync](/reference/system/xstore/xstore_members)
    * [Result](/reference/system/xstore/xstore_members)
  * 结构体
    * [XStoreProduct](/reference/system/xstore/xstore_members)
* [XPackage（API 内容）](/reference/system/xstore/xstore_members)

## 另请参阅

[商务概述](/publishing/xstore-commerce/xstore-commerce-overview)<br />[XStore API 参考](/reference/system/xstore/xstore_members)


## Related topics

- [排查 XStore 开发问题](/zh-CN/publishing/xstore-commerce/xstore-troubleshooting.md)
- [XStoreIsLicenseValid](/zh-CN/reference/system/xstore/functions/xstoreislicensevalid.md)
- [XStoreCanAcquireLicenseForPackageResult](/zh-CN/reference/system/xstore/functions/xstorecanacquirelicenseforpackageresult.md)
- [XStoreCanAcquireLicenseForStoreIdResult](/zh-CN/reference/system/xstore/functions/xstorecanacquirelicenseforstoreidresult.md)
- [XStoreCloseLicenseHandle](/zh-CN/reference/system/xstore/functions/xstorecloselicensehandle.md)