Contents

掉宝技术指南

目录

引言

本页面讨论设置掉宝系统的技术先决条件，以及为您的游戏选择合适的掉宝交付机制时必须考虑的因素。本文仅作为技术指南，在设计系统之前应仔细阅读，并在构建系统的过程中予以参考。

组织和游戏所有权

在创建掉宝活动之前，您必须拥有一个 开发人员组织 ，且该组织目前拥有您希望为其创建掉宝活动的游戏类别的所有权。请咨询您的公司以确认此类组织是否已存在。如果不存在，请参阅注册和管理组织以了解有关如何创建组织的信息。

如果您的组织名下没有分配到您的游戏，您将需要请求游戏的所有权。请参阅游戏管理以了解有关如何在 Twitch 上请求游戏类别所有权的信息。

您需要等待组织和游戏所有权请求均获得批准后才能继续。如果您刚刚才提交这些请求，可能需要 1-2 周的时间才能获得批准。为了避免组织申请被拒绝的常见问题，请参阅 为什么我的组织请求被拒绝了？

账户关联

为了领取游戏内奖励，Twitch 观众需要关联他们的 Twitch 账户和游戏账户。从 Twitch 的角度来看， 账户关联 是指用户通过您的应用程序（客户端 ID）进行身份验证，从而在用户的 Twitch 账户和您的第三方应用程序之间建立关联。

获取您的客户端 ID

您必须拥有一个客户端 ID（也称为 应用程序 ），且该 ID 须由属于您组织成员的用户所拥有。如果您还没有客户端 ID，请按照注册您的应用程序中概述的步骤进行操作。建议使用共享的公司账户来创建此应用程序，因为 Twitch 上的应用程序无法转移。

此建议至关重要，因为若员工离职后其个人账户仍持有该应用程序的所有权，将导致您的组织无法更改该应用程序。

设置您的账户关联流程

当用户的账户未关联到您的应用程序时，他们将被重定向到您的网站以完成账户关联流程。为了正确关联 Twitch 和游戏账户，您需要遵循以下流程：

  1. 要求观众登录您的账户系统
  2. 要求观众使用其 Twitch 账户授权您的 Twitch 应用程序
  3. 在您的系统中存储 Twitch 账户 <> 游戏账户的映射关系

具体而言，我们建议您存储以下信息：

虽然账户关联可以在游戏内实现，但我们建议您托管一个网页以便 Twitch 观众关联他们的账户。您可以将用户进行账户关联的页面 URL 添加到您的活动配置中，这样 Twitch 就能将您的观众重定向到正确的账户关联页面。

有关根据您的客户端 ID 验证用户的信息，请参阅Twitch OAuth 指南。掉宝最常见的验证形式是“隐式授权模式”（Implicit Grant Flow）和“授权码模式”（Authorization Code Grant Flow）。在这些步骤中使用的客户端 ID 必须 是本页面上文讨论过的客户端 ID，否则账户关联流程将无法生效。

处理账户取消关联

用户可能随时断开其 Twitch 账户与游戏账户之间的账户关联，无论是有意还是无意。这种情况可能发生在以下几种情形中，例如当用户：

无论何种情况，这总是因为用户授予您的客户端 ID 的授权被撤销或移除了。要检查用户是否已断开其账户连接，您可以检查其 OAuth 令牌的有效性。

用户在取消关联后可以重新关联其账户。关于处理用户的账户重新关联，我们提供以下建议：

为了处理上述情况，建议您将掉宝发放数据与 Twitch 用户 ID 或游戏内账户 ID，连同 活动 ID + 奖励 ID 配对信息一并存储。请注意，同一个奖励 ID 可能会在多个活动 ID 中被多次使用。

移除账户关联

您可以随时出于任何原因终止用户的账户关联。由于账户关联主要由您维护，您需要在您的游戏账户系统内移除这些关联。

出于安全考量，我们还建议您撤销 OAuth 访问令牌。目前无法从用户视角的 Twitch 账户端移除该账户关联的显示状态。如果用户希望重新连接其账户，则需要在 Twitch 上手动移除该连接。

设计您的掉宝系统

Twitch 允许您利用 Twitch API 和 EventSub 来接收有关您掉宝活动的信息。如何利用这些系统，取决于从技术角度来看您的游戏库存系统的可用性。

您可以设置三种推荐的掉宝系统：

如果您不确定该使用哪种方式，大多数情况下会选择使用 EventSub + Twitch API 或 Twitch API（离线库存） 。如果您的权益交付系统由您运营的服务器处理，请遵循 EventSub + Twitch API 指南。如果您的游戏权益系统无法访问服务器，请遵循 Twitch API（离线库存） 指南。

EventSub + Twitch API

最常见的掉宝系统会同时利用 Twitch API 和 EventSub 。在这种情境下，掉宝权益将通过 EventSub Webhooks 推送到您托管的 URL 端点，进而激活您的游戏权益系统以在游戏内发放物品。在成功发放游戏内物品后，您需要调用 Twitch API，以便在 Twitch 系统中记录该奖励已完成兑现。

技术细节

在激活以下流程之前，我们假定用户已按照账户关联中的描述，关联了其 Twitch 账户和游戏账户。

EventSub + Twitch API 技术详情图表

如上图所示，将部署以下系统：

在设置 EventSub 订阅时，您需要使用 App Access Token （应用程序访问令牌）。建议在调用 API 时使用相同的 App Access Token（应用程序访问令牌），因为这允许您一次性批量更新大量用户。

EventSub 设置

注意： 在开始实施之前，请先通读技术常见问题解答，以了解在构建掉宝系统时可能遇到的常见问题和状况。

EventSub 订阅类型

Twitch 的 EventSub 产品允许您监听您请求的实时事件，这些事件被称为订阅类型。drop.entitlement.grant 订阅类型会在掉宝权益发放给观众时发送通知。有关此 EventSub 主题的详细信息，请参阅掉宝权益发放。

要订阅 EventSub 主题，请按照“订阅事件”中的步骤操作。对于此特定订阅类型，您需要在条件中纳入您的 organization_id，并可选择纳入 category_id 和 campaign_id。在大多数情况下，您只需定义 organization_id，因为定义其他字段只会传递经这些字段过滤后的掉宝通知。

此订阅类型还要求您在 EventSub 订阅中纳入 is_batching_enabled。这是因为与大多数 EventSub 订阅不同，此订阅可以在单个通知中纳入多个掉宝事件。

实施

您的权益系统 是掉宝集成的核心。该系统负责处理传入的 EventSub Webhook，与您游戏的用户数据库和库存系统进行通信，并在完成后更新 Twitch API。

如上图所述，您的系统应完成以下操作：

接受掉宝权益发放

首先，每当一个或多个用户完成了掉宝活动时，Twitch 的 EventSub 系统将向您发送通知。在 EventSub 通知中，您将看到一个包含以下格式掉宝数据的数组：

[
    {
        "id": "bf7c8577-e3e3-4881-a78a-e9446641d45d",
        "data": {
            "organization_id": "373c8318-78e7-4bc5-bf2f-7a1a48a1d7d4",
            "category_id": "26936",
            "category_name": "Music",
            "campaign_id": "9003e09a399c-256e-11f0-8869-0a58a9feac02",
            "user_id": "141981764",
            "user_name": "TwitchDev",
            "user_login": "twitchdev",
            "entitlement_id": "WW91IGFyZW4ndCBzdXBwb3NlZCB0byBkZWNvZGUgdGhlc2UhIQ==",
            "benefit_id": "your-custom-reward-id-ends-up-here",
            "created_at": "2019-01-28T04:17:53.325Z"
        }
    },
    ...
]

由于可能会返回多个权益，单个 EventSub 通知中可能会列出多个用户。您需要遍历有效负载数组中的所有权益，并临时存储哪些权益正发放给哪些用户。

从您的数据库获取用户信息

当用户关联其账户时，您的数据库中应有一条记录，用于关联用户的 Twitch 账户与其游戏账户。此信息对于通知游戏将掉宝奖励发放给哪位用户至关重要。

如果用户不存在于您的数据库中，则表示该用户尚未关联其账户。您此时需要忽略该通知，并在稍后进行处理。您有义务在活动结束后 14 天内尝试处理此权益。

将信息转发到您的游戏以便在游戏内发放权益

既然您已获取所需信息，便可以将 benefit_id 和 游戏内用户 ID 转发到您的游戏后端服务器。在继续后续步骤之前，您需要与您的系统确认游戏内物品已正确发放至用户的库存中。

调用 Twitch API 将权益标记为已兑现

使用 Update Drops Entitlements API，您将通知 Twitch 权益已完成兑现。您可以参考类似于此 curl 请求的方式调用 API：

curl -X PATCH 'https://api.twitch.tv/helix/entitlements/drops' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>' \
-H 'Content-Type: application/json' \
-d '{
    "fulfillment_status": "FULFILLED",
    "entitlement_ids": [
        "U2VyaW91c2x5LCBkb24ndCB3b3JyeSBhYm91dCBkZWNvZGluZyB0aGVzZSE=",
        "R28gcmVhZCB0aGUgVGVjaG5pY2FsIEZBUSBmb3IgbW9yZSBpbmZv"
    ]
}'

您需要使用 App Access Token（应用程序访问令牌）进行此调用，因为此 API 调用可能会影响多个用户。有关此 API 的更多信息（包括示例有效负载响应），请参阅 Update Drops Entitlements API（更新掉宝权益 API）。

结语

常见的一种情况是账户未关联。如果收到未关联账户的通知，您需要重新尝试发放游戏内物品权益，直到成功为止，或者直到活动结束后已过去 14 天。

此外，此实现依赖于 EventSub 向其推送信息，而不会检查 API 是否存在遗漏信息。虽然 EventSub 确实会尝试重新发送失败的通知，但在极少数情况下，通知可能无法送达。为解决此问题，建议做好准备手动搜索 Get Drops Entitlements API（获取掉宝权益 API），查找从未从 CLAIMED（已领取）变为 FULFILLED（已兑现） 的权益。

Twitch API（托管库存）

如果您不希望托管 Web 服务器来处理传入的 EventSub Webhooks，可以改为定期调用 Twitch API。在此方案中，建议您每隔 5-15 分钟检查一次 Twitch API，查看用户是否有未兑换的掉宝，然后将游戏内物品发放至用户的游戏账户。在成功发放游戏内物品后，您需要调用 Twitch API，以便在 Twitch 系统中记录该奖励已完成兑现。

技术细节

在激活以下流程之前，我们假定用户已按照账户关联中的描述，关联了其 Twitch 账户和游戏账户。

Twitch API（托管库存）技术详情图表

如上图所示，将部署以下系统：

此设置建议使用 User Access Token （用户访问令牌），但如果需要，您也可以使用 App Access Token （应用程序访问令牌）。如果使用 User Access Token （用户访问令牌），您需要为每个用户单独调用 Update Drop Entitlements （更新掉宝权益）。

注意： 在开始实施之前，请先通读技术常见问题解答，以了解在构建掉宝系统时可能遇到的常见问题和状况。

实施

您的权益系统 是掉宝集成的核心。该系统将在其中一个时刻激活：

系统激活后，会调用 Twitch API 获取所有未兑现权益的列表，接着与您游戏的用户数据库和库存系统进行通信，并在完成后更新 Twitch API。

如上图所述，您的系统应完成以下操作：

调用 Twitch API 获取权益列表

使用 Get Drops Entitlements API，您可以获取有关您游戏的所有未兑现权益的信息。您可以参考类似于此 curl 请求的方式调用 API：

curl -H GET 'https://api.twitch.tv/helix/entitlements/drops?game_id=<Your game ID>&fulfillment_status=CLAIMED' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>'

如果您使用的是 User Access Token （用户访问令牌），API 将只返回该用户的权益。如果您使用 App Access Token （应用程序访问令牌），API 将返回所有用户的权益，除非您在查询参数中指定了user_id。

从您的数据库获取用户信息

当用户关联其账户时，您的数据库中应有一条记录，用于关联用户的 Twitch 账户与其游戏账户。此信息对于通知游戏将掉宝奖励发放给哪位用户至关重要。

如果用户不存在于您的数据库中，则表示该用户尚未关联其账户。您此时需要忽略该通知，并在稍后进行处理。您有义务在活动结束后 14 天内尝试处理此权益。

将信息转发到您的游戏以便在游戏内发放权益

既然您已获取所需信息，便可以将 benefit_id 和 游戏内用户 ID 转发到您的游戏后端服务器。在继续后续步骤之前，您需要与您的系统确认游戏内物品已正确发放至用户的库存中。

调用 Twitch API 将权益标记为已兑现

使用 Update Drops Entitlements API，您将通知 Twitch 权益已完成兑现。您可以参考类似于此 curl 请求的方式调用 API：

curl -X PATCH 'https://api.twitch.tv/helix/entitlements/drops' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>' \
-H 'Content-Type: application/json' \
-d '{
    "fulfillment_status": "FULFILLED",
    "entitlement_ids": [
        "U2VyaW91c2x5LCBkb24ndCB3b3JyeSBhYm91dCBkZWNvZGluZyB0aGVzZSE=",
        "R28gcmVhZCB0aGUgVGVjaG5pY2FsIEZBUSBmb3IgbW9yZSBpbmZv"
    ]
}'

如果您使用 User Access Token （用户访问令牌），当您尝试修改未与该令牌关联的用户的权益状态时，API 会返回错误。如果您使用 App Access Token （应用程序访问令牌），只要权益关联的游戏属于客户端 ID 所有者所在的组织，您就可以使用此 API 调用来修改这些权益。

结语

常见的一种情况是账户未关联。来自这些账户的权益仍会显示为 CLAIMED（已领取）状态，但在用户采取行动之前无法进行兑现。如果您是自动处理权益，则需要不断重试发放游戏内物品权益，直到成功为止，或者直到活动结束 14 天后。如果您是根据用户交互进行处理，请通知用户其需要完成账户关联，才能收到掉宝奖励。

Twitch API（离线库存）

无需托管用户库存的场景下（例如单人游戏），您可以在本地托管游戏。

账户关联

此场景下的账户关联流程略有不同，因为 OAuth 令牌需要在本地存储。由于假定游戏是完全离线的，我们需要一个本地 Web 服务器来处理 OAuth 连接。

Twitch API（离线库存）账户关联图表

如上图所示，将部署以下系统和实体：

要让用户将账户关联至您的游戏，需要完成以下操作流程：

注意： User Access Token（用户访问令牌）的时效较短，且通过隐式授权流程 (Implicit Grant Flow) 提供的令牌不包含刷新令牌。因此，您需要不时地验证您的令牌，例如在游戏启动时以及用户发起掉宝检查时。

技术细节

Twitch API（离线库存）技术详情图表

如上图所示，将部署以下系统和实体：

实施

当用户手动发起请求检查未兑现的掉宝奖励时，该系统启动。此类请求通常通过游戏内设置 UI 中的“ 检查掉宝 ”按钮触发。激活后，系统会验证本地存储的 OAuth 令牌，调用 Twitch API 获取所有未兑现权益的列表，接着与您游戏的库存系统通信，并在完成后更新 Twitch API。

如上图所述，您的系统应完成以下操作：

验证存储的 OAuth 令牌

User Access Token（用户访问令牌）的时效较短，且通过隐式授权流程 (Implicit Grant Flow) 提供的令牌不包含刷新令牌。因此，在调用 Twitch API 之前，您需要验证您的令牌。或者，您可以尝试直接调用 API，如果令牌已过期，API 将返回 HTTP 401 Unauthorized 。

如果令牌已过期，您需要引导用户点击 与 Twitch 连接 （Connect with Twitch）按钮重新关联账户。

调用 Twitch API 获取权益列表

使用 Get Drops Entitlements API，您可以获取有关您游戏的所有未兑现权益的信息。您可以参考类似于此 curl 请求的方式调用 API：

curl -H GET 'https://api.twitch.tv/helix/entitlements/drops?game_id=<Your game ID>&fulfillment_status=CLAIMED' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>'

必须使用前文提到的 User Access Token （用户访问令牌）进行此调用。该调用将自动仅返回当前正在游玩您游戏的玩家信息。

验证是否存在未兑现的权益

在此系统中，用户可以随时发起掉宝权益检查。因此，可能并没有任何掉宝权益需要兑现。请处理 API 响应，并在继续下一步之前验证是否存在需要兑现的权益。

调用 Twitch API 将权益标记为已兑现

使用 Update Drops Entitlements API，您将通知 Twitch 权益已完成兑现。您可以参考类似于此 curl 请求的方式调用 API：

curl -X PATCH 'https://api.twitch.tv/helix/entitlements/drops' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>' \
-H 'Content-Type: application/json' \
-d '{
    "fulfillment_status": "FULFILLED",
    "entitlement_ids": [
        "U2VyaW91c2x5LCBkb24ndCB3b3JyeSBhYm91dCBkZWNvZGluZyB0aGVzZSE=",
        "R28gcmVhZCB0aGUgVGVjaG5pY2FsIEZBUSBmb3IgbW9yZSBpbmZv"
    ]
}'

此步骤可以在游戏内发放物品之前或之后执行，但在游戏内发放之前执行可以避免库存系统出现某些竞态条件 (Race Conditions)。此调用的目的是防止用户重复领取同一件游戏内物品。

如果 API 调用因任何原因（如令牌过期或无网络连接）失败，您需要通知玩家失败原因，并提供相应的故障排除指引。

更新游戏内库存以纳入奖励物品

由于该系统完全在您的游戏内部运行，您现在可以调用游戏的库存系统进行更新，将与权益关联的奖励物品纳入。

通知玩家奖励已成功发放。

现在可以将玩家重定向回游戏，让其享受收到的游戏内物品！

技术常见问题解答

我需要为用户的掉宝申领兑现提供多久的支持期限？

开发者必须在活动结束后的 14 天内，为已申领并关联账户的观众兑现奖励。对于某些时效性强的活动（如限时 Beta 测试），此要求可以豁免。

奖励在活动结束后还能领取吗？

可以。用户必须在活动期间满足获得掉宝的要求，但在活动结束后最多 14 天内，用户仍可关联账户并进行领取。当发生这种情况时，您可能会收到 EventSub 通知，且 Twitch API 提供的数据也会更新。

EventSub 和 Twitch API 提供的 ID 有最大长度限制吗？

ID 没有强制的最大长度，因为 ID 是不透明数据且可能发生变化。如果您的数据库需要设定最大长度，建议设置为 255 以保持灵活性。

我应该验证奖励 ID 的格式或对其解码吗？

不应该。Twitch API 和 EventSub 提供的掉宝相关 ID 是不透明的，解码后的信息没有实际意义。ID 的格式也可能随时更改，因此请勿依赖特定格式 （如 GUID 或 Base64 ）来验证 ID。

奖励在账户关联之前可以进行领取吗？

可以，用户可以在关联账户之前领取掉宝奖励。在这种情况下，您需要持续检查用户是否关联账户，直到关联完成。该要求仅在活动结束后最多持续 14 天，超过该期限用户将无法再领取奖励。

我需要将掉宝权益标记为 FULFILLED（已兑现）吗？

是的。除了通过 Twitch API 将掉宝权益标记为“已兑现”之外，没有其他途径可以回溯确认其是否已成功兑现。即使是使用 EventSub 的系统，这样做也很有必要，因为在极少数情况下，您的 EventSub 系统可能会在活动期间宕机，从而遗漏新的掉宝权益。

API 返回结果有顺序吗？

没有。Get Drops Entitlement API 返回的结果没有预设顺序，结果返回的顺序可能与其任何属性都无关。若要更好地搜索具有特定属性（如兑现状态）的权益，请在调用 API 时使用查询参数。

为什么用户尝试关联账户后未显示账户得到关联？

掉宝活动的账户关联是否成功，取决于用户是否成功通过在“掉宝设置”中绑定的游戏客户端 ID 进行身份验证。请确保“掉宝设置”中的客户端 ID 与您在前文“账户关联”部分设置的“ 与 Twitch 连接 ”（Connect with Twitch）链接所使用的客户端 ID 一致。

注意： 如果您在创建掉宝活动后更改了“掉宝设置”中的游戏客户端 ID，则需要创建一个新的活动，以便与游戏新分配的客户端 ID 同步。

Docs Status Support Showcase Blog