# Drops技術ガイド

Source: https://dev.twitch.tv/docs/ja/drops/technical-guide/

## はじめに {#introduction}

このページでは、Dropsシステムをセットアップするための技術的な前提条件と、あなたのゲームに適切なDrops配信メカニズムを選択するための考慮事項について説明します。これは技術的なガイドのみを目的としており、システムを設計する前に慎重に確認し、システムを構築する過程で参照する必要があります。

## 組織とゲームの所有権 {#organization-and-game-ownership}

Dropsキャンペーンを作成する前に、Dropsキャンペーンの作成を希望するゲームカテゴリーの所有権を現在保持している **デベロッパー組織** が必要です。そのような組織がすでに存在するかどうかは会社に確認してください。存在しない場合、組織の作成方法については、[組織の登録および管理](https://dev.twitch.tv/docs/companies.md#registering-and-managing-organizations)をご覧ください。

組織にゲームが割り当てられていない場合は、ゲームの所有権を要求する必要があります。Twitchであなたのゲームカテゴリーの所有権をリクエストする方法については、[ゲーム管理](https://dev.twitch.tv/docs/companies.md#game-management)をご覧ください。

手続きを続行するには、組織とゲームの所有権の両方が承認されるのを待つ必要があります。これらのリクエストを行ったばかりなら、承認されるまでに1～2週間かかる場合があります。組織のリクエストが拒否されるという問題がよくあるのですが、これを避けるために、[組織リクエストが拒否された理由](https://dev.twitch.tv/docs/companies.md#why-was-my-organization-request-rejected)をご覧ください。

## アカウントのリンク {#account-linking}

ゲーム内報酬を獲得するには、Twitchの視聴者がTwitchアカウントとゲームアカウントをリンクする必要があります。Twitchからすると、 **アカウントリンク** とは、ユーザーがアプリケーション（クライアントID）に対して認証を行い、ユーザーのTwitchアカウントとサードパーティアプリケーションとの間にリンクを作成することを言います。

### クライアントIDの取得 {#getting-your-client-id}

組織の一員であるユーザーが所有するクライアントID（ *アプリケーション* ）を用意する必要があります。まだお持ちでない場合は、[アプリを登録](https://dev.twitch.tv/docs/authentication/register-app.md)に概要が記載された手順に従ってください。Twitchではアプリケーションは譲渡できないため、このアプリケーションを作成するアカウントは共有された企業アカウントにすることをお勧めします。

従業員が個人アカウントでアプリケーションを所有したまま、組織を離れる可能性があり、そうなると組織がアプリケーションに変更を行うことができなくなるため、これは非常に重要です。

### アカウントリンクプロセスの設定 {#setting-up-your-account-linking-process}

ユーザーが自分のアカウントをあなたのアプリケーションにリンクしていない場合、そのユーザーは、アカウントリンクのプロセスを完了するために、あなたのウェブサイトにリダイレクトされます。Twitchとゲームアカウントを正しくリンクするには、以下のプロセスに従う必要があります。

1. 視聴者にアカウントシステムにログインするよう依頼します
2. 視聴者にTwitchアカウントでTwitchアプリケーションを承認するよう依頼します
3. Twitchアカウント <> ゲームアカウントのマッピングを保存します

具体的には、次の情報を保存することをお勧めします。

* ゲームアカウントID
* Twitch OAuthトークン
* Twitchリフレッシュトークン
* TwitchユーザーID

アカウントのリンクはゲーム内で行うことができますが、Twitchの視聴者にアカウントをリンクしてもらえるようにウェブページで誘導することをお勧めします。Twitchが正しいアカウントリンクページに視聴者をリダイレクトできるように、ユーザーがアカウントをリンクするページのURLをキャンペーン設定に追加できます。

クライアントIDに対するユーザーの認証の詳細については、[Twitch OAuthガイド](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth.md)をご覧ください。Dropsの認証方法として最も一般的なのは [Implicit Grant Flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth.md#implicit-grant-flow)と [Authorization Code Grant Flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth.md#authorization-code-grant-flow)です。これらの手順で使用するクライアントIDは、このページで前述したクライアントID **でなければなりません** 。そうでない場合、アカウントリンクの手順が機能しません。

### アカウントのリンク解除の取り扱いについて {#handling-account-de-linking}

ユーザーは、Twitchアカウントとゲームアカウントの間のリンクを、意図的にせよ無意識にせよ、いつでも解除することができます。これは以下のような行動をユーザーが取った場合に発生する可能性があります。

* パスワードを変更する
* Twitchから[利用を凍結](https://help.twitch.tv/s/article/about-account-suspensions-dmca-suspensions-and-chat-bans?language=en_US#AccountEnforcements)された
* 対象のアカウントの[接続](https://www.twitch.tv/settings/connections)ページ内で、手動で接続を解除する
* OAuthトークンとリフレッシュトークンの両方が期限切れになる
  * **注意:** OAuthトークン **のみ** が期限切れになった場合は、アカウントリンクは自動で解除されません。この場合、両方のトークンが期限切れにならなくてはなりません。

いずれの場合でも、あなたのクライアントIDに付与されたユーザーの認証が取り消されたかまたは削除されたことが理由となります。ユーザーがアカウントを接続解除したかどうかを確認するには、OAuthトークンの[有効性を確認します](https://dev.twitch.tv/docs/authentication/validate-tokens.md)。

ユーザーはリンクを解除した後にアカウントを再度リンクすることが可能です。ユーザーのアカウント再リンクに関する推奨事項をいくつか提示します：

* **ゲーム内アイテムの付与は、1ユーザーID当たり1回限り** – Twitchアカウントをゲームアカウントにリンクし、ゲーム内コンテンツを利用したユーザーは、同じTwitchアカウントを2番目のゲームアカウントに再びリンクし、同じゲーム内アイテムを利用することはできません。
* **TwitchアカウントがDropsを受け取れるのは、ゲーム内で1回のみ** \- Twitchアカウントをゲームアカウントにリンクし、ゲーム内コンテンツを利用したユーザーは、同じTwitchアカウントを別のゲームアカウントに再びリンクし、同じゲーム内アイテムを取得することはできません。
* **ユーザーは複数のTwitchアカウントを利用して、ひとつのDropsを重複して入手することはできない** – Twitchアカウントをゲームアカウントにリンクしたユーザーは、リンクを解除して別の資格のあるTwitchアカウントを同じゲームアカウントにリンクしても追加のゲーム内コンテンツを利用することはできません。
* **Dropsは譲渡不可** – Twitchアカウントをゲームアカウントにリンクしたユーザーは、利用済みの商品を別のゲームアカウントに譲渡できません（例：Steamのマーケットプレイスでコンテンツを別のゲームアカウントに転送する。

上記の場合に対処するために、キャンペーンIDと報酬IDの *組み合わせ* に加えて、TwitchユーザーIDまたはゲーム内アカウントIDに関連するDrops許可データの保存をお勧めします。報酬IDは複数のキャンペーンIDにおいて複数回使用できます。

### アカウントリンクの削除 {#removing-an-account-link}

いかなる理由であれ、いつでもユーザーのアカウントリンクを終了することができます。アカウントリンクは主に管理するのはあなたなので、あなたがゲームのアカウントシステム内でリンクを削除する必要があります。

セキュリティ上の理由から、[OAuthアクセストークンを取り消す](https://dev.twitch.tv/docs/authentication/revoke-tokens.md)ことをおすすめします。ユーザーのTwitchアカウントから、アカウントリンクが表示されないようにする方法はありません。ユーザーがアカウントに再リンクしたい場合は、Twitch上のリンクを手動で削除する必要があります。

## Dropsシステムの設計 {#designing-your-drops-system}

Twitchでは、Twitch APIとEventSubの両方を使用して、Dropsキャンペーンに関する情報を取得できます。これらのシステムをどう活用するかは、技術的な観点から、ゲームのインベントリシステムが利用可能かどうかによって異なります。

設定可能な推奨Dropsシステムには以下の3種類があります。

* **EventSub \+ Twitch API** – このシステムでは、EventSub経由でDropsエンタイトルメントに関する情報をあなたのウェブサーバーに直接受信し、これらのエンタイトルメントが履行された時にTwitch APIを使用してTwitchに通知することができます。ライブサービスゲーム含め、ほとんどの場合この方法が最も推奨されます。
* **Twitch API \(ホストされたインベントリ\)** – このシステムでは、リクエストに応じてDropsのエンタイトルメントに関する情報を取得できますが、自動的にシステムに通知されることはありません。これはあまり推奨されませんが、ユーザーリクエストがあった際にDropsのステータスを確認したい、という場合に役立ちます。
* **Twitch API（オフラインインベントリ）** – ゲーム内アイテムがオンラインでホストされず、Dropsエンタイトルメントまたはインベントリ管理のためのオンラインサーバーにアクセスできないゲームは、ゲーム内からTwitch APIにアクセスしてDropsエンタイトルメントシステムを処理しなければなりません。

何を使用すべきか分からないのであれば、ほとんどの場合は、 *EventSub \+ Twitch API* または *Twitch API（オフラインインベントリ）* を使用します。エンタイトルメント配信システムが貴社で運営するサーバーによって処理される場合は、 **EventSub \+ Twitch API** のガイドに従ってください。ゲームのエンタイトルメントシステムがサーバーにアクセスできない場合は、 **Twitch API\(オフラインインベントリ\)** のガイドに従ってください。

## EventSub + Twitch API {#eventsub--twitch-api}

最も一般的なDropsシステムでは、 **Twitch API** と **EventSub** の両方を利用します。この場合は、Dropsのエンタイトルメントは、EventSub Webhookを使用して、貴社がホストしているURLエンドポイントにプッシュされます。これにより、貴社のゲームのエンタイトルメントシステムがアクティベートされ、ゲーム内でアイテムをお届けできるようになります。ゲーム内アイテムのお届けが完了したら、Twitch APIを呼び出して、報酬が付与されたことをTwitchのシステム内に登録します。

### 技術的な詳細 {#technical-details}

以下のプロセスがアクティベートされる前に、ユーザーは[アカウントのリンク](#account-linking)で記載された方法でTwitchアカウントとゲームアカウントをリンクしているものとみなされます。

![EventSub + Twitch API技術詳細チャート](https://dev.twitch.tv/docs/assets/images/drops/ja/eventsub-and-twitch-api-technical-chart.png)

上記の図では、次のシステムが用意されます。

* **エンタイトルメントシステム** – これは、EventSub Webhookを承認し、[Dropsエンタイトルメントの付与](https://dev.twitch.tv/docs/eventsub/reference/drop.md#drop-entitlement-grant)のEventSubペイロードを提供する独自のサービスです。
* **EventSub** – Twitchの[EventSub](https://dev.twitch.tv/docs/eventsub.md)製品です。ユーザーがDrops報酬の対象になった際に、Webhook通知をあなたに送信します。
* **Twitch API** – TwitchのAPIです。Dropsエンタイトルメントのステータスに関する情報を更新するためにコールを行います。
* **ゲームユーザーデータベース** – これはTwitchユーザーIDとゲーム内アカウントシステムのユーザー識別子との関連を検索できるサービスのことを指します。この関連はアカウントリンクのプロセス中に設定されます。
* **ゲーム内インベントリ** – インベントリシステムにアイテムを付与できるサービスです。

EventSubサブスクを設定する際には、 **App Access Token** を使用する必要があります。APIを呼び出す際には、同じApp Access Tokenを使用することをお勧めします。これにより、一度に大量のユーザーを更新できるようになります。

### EventSubの設定 {#eventsub-setup}

**注意:** 実装を開始する前に、まず[よくある技術的な質問](#technical-faq)を読んで、Dropsシステムを構築する際に発生するよくある質問や問題を確認してください。

#### EventSubサブスクタイプ {#eventsub-subscription-type}

Twitchの[EventSub](https://dev.twitch.tv/docs/eventsub.md)製品は、あなたがリクエストしたリアルタイムのイベントを聞くことができます。これはサブスクタイプとされます。`drop.entitlement.grant`というサブスクの種類は、Dropsのエンタイトルメントが視聴者に付与されると通知を送信します。このEventSubトピックの詳細については、[Drop Entitlement Grant](https://dev.twitch.tv/docs/eventsub/reference/drop.md#drop-entitlement-grant)を参照してください。

EventSubトピックにサブスクライブするには、[イベントへのサブスクライブ](https://dev.twitch.tv/docs/eventsub/manage-subscriptions.md#subscribing-to-events)の手順に従ってください。この特定のサブスクタイプでは、条件内に`organization_id`を含める必要があります。また、任意で`category_id`と`campaign_id`を含めることもできます。ほとんどの場合は、`organization_id`を定義するだけで済みます。他の定義はこれらのフィールドでフィルタリングされたDrops通知を提供するのみです。

このサブスクタイプでは、EventSubサブスクに`is_batching_enabled`を含める必要があります。これは、ほとんどのEventSubサブスクと異なり、このサブスクが1つの通知内に複数のDropsイベントを含めることができるためです。

### 実装 {#implementation}

**エンタイトルメントシステム** は、Drops統合の核となるものです。このシステムは受け取ったEventSub Webhookを処理し、ゲームのユーザーデータベースやインベントリシステムと通信し、完了後にTwitch APIを更新します。

上記の表に記載されているように、システムは以下の操作を完了する必要があります。

#### Dropsエンタイトルメントの付与を承諾する {#accept-drop-entitlement-grants}

まず、1人以上のユーザーがDropsキャンペーンを完了した際に、TwitchのEventSubシステムから通知が送信されます。EventSub通知内には、この形式のDropsデータの配列が表示されます。

```json
[
    {
        "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"
        }
    },
    ...
]
```

複数のエンタイトルメントが返される可能性があるため、1つのEventSub通知に複数のユーザーがリストされる可能性があります。ペイロードの配列内のすべてのエンタイトルメントをスキャンし、どのエンタイトルメントがどのユーザーに付与されるのかを一時的に保存する必要があります。

#### あなたのデータベースからユーザー情報を取得 {#get-user-information-from-your-database}

ユーザーがアカウントをリンクする場合、そのユーザーのTwitchアカウントとゲームアカウントとの間のリンクに関連づけられたデータベースエントリをどこかに用意する必要があります。この情報はDrops報酬を付与する対象をゲームに通知するために必要になります。

ユーザーがデータベース内に存在しない場合は、そのユーザーはまだアカウントをリンクしていません。この時点では通知を無視して、あとで処理する必要があります。あなたはキャンペーン終了から14日の時点まで、このエンタイトルメントの処理を試みる義務があります。

#### ゲーム内で資格を得るために情報をゲームに転送する {#forward-information-to-your-game-to-be-entitled-in-game}

これで必要な情報が得られたので、 **benefit\_id** と **ゲーム内のユーザーID** をゲームのバックエンドサーバーに転送できます。その後、作業を続行する前にゲーム内アイテムがユーザーのインベントリに適切に付与されているかどうかをシステムで確認することをお勧めします。

#### Twitch APIを呼び出し、エンタイトルメントを履行済みとしてマークする {#call-the-twitch-api-to-mark-the-entitlements-as-fulfilled}

[Update Drops Entitlements API](https://dev.twitch.tv/docs/api/reference/entitlements.md#update-drops-entitlements)を使用して、エンタイトルメントが履行されたことをTwitchに通知します。この *curl* リクエストと類似のAPIを呼び出すことができます。

```shell
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"
    ]
}'
```

このAPIコールは複数のユーザーに影響を与える可能性があるため、App Access Tokenを使用してコールを行う必要があります。ペイロードレスポンスの例など、このAPIの詳細については、[Update Drops Entitlements API](https://dev.twitch.tv/docs/api/reference/entitlements.md#update-drops-entitlements)を参照してください。

#### 最後に {#final-thoughts}

よくあるケースとしては、リンクされていないアカウントが原因です。リンクされていないアカウントに通知が送信された場合、成功するか、キャンペーンの終了から14日が経過するまで、ゲーム内アイテムの付与を再度試みる必要があります。

さらに、この実装はEventSubにプッシュされる情報に依存し、APIで情報が欠けているか確認しません。EventSubは失敗した通知の再送信を試みますが、ごくまれに通知が届かない場合があります。この問題を解決するために、[Get Drops Entitlements API](https://dev.twitch.tv/docs/api/reference/entitlements.md#get-drops-entitlements)で、`CLAIMED`から`FULFILLED`まで処理されていないエンタイトルメントを手動で検索できるようにしておくことを推奨します。

## Twitch API (ホストされたインベントリ) {#twitch-api-hosted-inventory}

受け取ったEventSub Webhookを処理するためにウェブサーバーをホストしたくない場合は、代わりに一定間隔でTwitch APIを繰り返し呼び出します。この場合は、5～15分の間隔でTwitch APIを確認することをお勧めします。そのユーザーの未利用のDropsを確認して、ゲーム内アイテムをユーザーのゲームアカウントに届けます。ゲーム内アイテムの受け取りが完了したら、Twitch APIを呼び出して、報酬が付与されたことをTwitchのシステム内に登録します。

### 技術的な詳細 {#technical-details-1}

以下のプロセスがアクティベートされる前に、ユーザーは[アカウントのリンク](#account-linking)で記載された方法でTwitchアカウントとゲームアカウントをリンクしているものとみなされます。

![Twitch API (ホストされたインベントリ) 技術詳細表](https://dev.twitch.tv/docs/assets/images/drops/ja/twitch-api-hosted-technical-chart.png)

上記の図では、次のシステムが用意されます。

* **エンタイトルメントシステム** – これは、EventSub Webhookを承認し、[Dropsエンタイトルメントの付与](https://dev.twitch.tv/docs/eventsub/reference/drop.md#drop-entitlement-grant)のEventSubペイロードを提供する独自のサービスです。
* **Twitch API** – TwitchのAPIです。Dropsエンタイトルメントのリストを入手し、Dropsエンタイトルメントのステータスに関する情報を更新するためにコールを行います。
* **ゲームユーザーデータベース** – これはTwitchユーザーIDとゲーム内アカウントシステムのユーザー識別子との関連を検索できるサービスのことを指します。この関連はアカウントリンクのプロセス中に設定されます。
* **ゲーム内インベントリ** – インベントリシステムにアイテムを付与できるサービスです。

このセットアップでは **User Access Token** を使用することが推奨されますが、必要に応じて **App Access Token** を利用することもできます。 *User Access Token* を利用する場合、User Access Tokenを使用している各ユーザーのために、個別に *Dropsエンタイトルメントの更新* を呼び出す必要があります。

**注意:** 実装を開始する前に、まず[よくある技術的な質問](#technical-faq)を読んで、Dropsシステムを構築する際に発生するよくある質問や問題を確認してください。

### 実装 {#implementation-1}

**エンタイトルメントシステム** は、Drops統合の核となるものです。このシステムは以下のいずれかのタイミングでアクティベートされます。

* 5～15分ごとに自動的でアクティベートされます。
* あなたのウェブサイトでのユーザーインタラクションなど、別のシステムによるアクティベーションがあった場合。

アクティベーションが完了すると、システムはTwitch APIを呼び出して未履行のすべてのエンタイトルメントのリストを取得し、ゲームのユーザーデータベースやインベントリシステムと通信し、完了後にTwitch APIを更新します。

上記の表に記載されているように、システムは以下の操作を完了する必要があります。

#### Twitch APIを呼び出し、エンタイトルメントのリストを取得する {#call-the-twitch-api-to-get-a-list-of-entitlements}

[Get Drops Entitlements API](https://dev.twitch.tv/docs/api/reference/entitlements.md#get-drops-entitlements)を使用して、ゲームの未履行エンタイトルメントすべてに関する情報を取得します。 *curl* リクエストと同様にAPIを呼び出すことができます。

```shell
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** を使用している場合、クエリパラメーターで`user_id`を特別に指定しない限り、APIはすべてのユーザーのエンタイトルメントを返します。

#### あなたのデータベースからユーザー情報を取得 {#get-user-information-from-your-database-1}

ユーザーがアカウントをリンクする場合、そのユーザーのTwitchアカウントとゲームアカウントとの間のリンクに関連づけられたデータベースエントリをどこかに用意する必要があります。この情報はDrops報酬を付与する対象をゲームに通知するために必要になります。

ユーザーがデータベース内に存在しない場合は、そのユーザーはまだアカウントをリンクしていません。この時点では通知を無視して、あとで処理する必要があります。あなたはキャンペーン終了から14日の時点まで、このエンタイトルメントの処理を試みる義務があります。

#### ゲーム内で資格を得るために情報をゲームに転送する {#forward-information-to-your-game-to-be-entitled-in-game-1}

これで必要な情報が得られたので、 **benefit\_id** と **ゲーム内のユーザーID** をゲームのバックエンドサーバーに転送できます。その後、作業を続行する前にゲーム内アイテムがユーザーのインベントリに適切に付与されているかどうかをシステムで確認することをお勧めします。

#### Twitch APIを呼び出し、エンタイトルメントを履行済みとしてマークする {#call-the-twitch-api-to-mark-the-entitlements-as-fulfilled-1}

[Update Drops Entitlements API](https://dev.twitch.tv/docs/api/reference/entitlements.md#update-drops-entitlements)を使用して、エンタイトルメントが履行されたことをTwitchに通知します。この *curl* リクエストと類似のAPIを呼び出すことができます。

```shell
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** を使用している場合は、このAPIコールを使用して、クライアントIDの所有者がメンバーになっている組織が所有するゲームに関連付けられたエンタイトルメントを変更できます。

### 最後に {#final-thoughts-1}

よくあるケースとしては、リンクされていないアカウントが原因です。これらのアカウントからのエンタイトルメントは、ユーザーのアクションが行われるまで履行できない場合でも、`CLAIMED`状態で表示されます。エンタイトルメントを自動的に処理する場合は、成功するまで、またはキャンペーンの終了から14日が経過するまで、ゲーム内アイテムの付与を再度試行する必要があります。ユーザーインタラクションに基づいて処理を行う場合は、Drops報酬を受け取るにはアカウントのリンクを完了する必要があることを、そのユーザーに通知してください。

## Twitch API (オフラインインベントリ) {#twitch-api-offline-inventory}

シングルプレイヤーゲームなど、ユーザーのインベントリをホストする必要がない場合は、ゲームをローカルでホストすることができます。

### コード例 {#code-sample}

オフラインインベントリの実装のデモを行うには、デバイスコードフロー\(DCF\)を使用するC\#コードサンプルの[drops\-csharp\-sample](https://github.com/twitchdev/drops-csharp-sample)リポジトリを参照してください。以下のセクションの説明にしたがって、ユーザー認証、Dropsエンタイトルメントの取得、利用状況の確認を行います。

### アカウントのリンク {#account-linking-1}

この場合のアカウントリンクのプロセスは少し異なり、OAuthトークンはローカルで保持する必要があります。ゲームが完全にオフラインであることが想定されているため、OAuth接続を処理するウェブサーバーをローカルで用意する必要があります。

![Twitch API (オフラインインベントリ) アカウントリンクチャート](https://dev.twitch.tv/docs/assets/images/drops/ja/twitch-api-offline-account-linking-technical-chart.png)

上記の図では、次のシステムと存在が用意されます。

* **プレイヤー** – ゲームをプレイしているユーザーです。
* **ゲーム** – あなたのゲームです。また、ローカルにホストされたHTTPサーバーを除いて、あなたのゲームのあらゆるビジュアルと背景の要素を含みます。
* **ゲームホスト型HTTPサーバー** – ゲームがバックグラウンドで開始するHTTPサーバーです。これは認証リダイレクトを処理するためだけに使用されます。
* **Twitch** – Twitchです。ユーザーは自分のアカウントをゲームにリンクできるように、Twitchにリダイレクトされます。このシステム内におけるTwitchの関連部分は、Twitchのログイン画面とTwitchのサードパーティアプリケーションの認証画面となります。

ユーザーが自分のアカウントをゲームにリンクすると、次の操作が完了します。

* **プレイヤー** がゲームの設定メニュー内の「 **Twitchに接続** 」ボタンをクリックします。
* ゲームのバックグラウンドで、ローカルにホストされたHTTPサーバーが起動します。このサーバーは、あなたのクライアントIDのリダイレクトURIに定義されているものと同じ **localhost** ポートでホストされる必要があります。これは[クライアントIDの取得](#getting-your-client-id)でセットアップします。
* あなたのゲームがプレイヤーのウェブブラウザを開き、自動的にTwitchの認証URLに移動させます。 **いかなる状況であれ** ゲーム内に、あなたのクライアントIDのクライアントシークレットを含めるべきではありません。そのため、[Implicit Grant Flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth.md#implicit-grant-flow)で定義されたURLを使用する必要があります。
* ユーザーがTwitchにサインインし、アプリケーションを認証すると、URLに含まれるアクセストークンで、ローカルホストのURLにリダイレクトされます。
* HTTPサーバーがこのリクエストを承認し、トークンをローカルで保存して、ブラウザのウィンドウを閉じるように指示するHTMLをユーザーに返します。
* ゲーム内の設定メニューUIを更新し、ユーザーにTwitchアカウントの接続が正常に完了したことを示します。

**注意：** User Access Tokenは有効期間が短く、Implicit Grant Flowで提供されるアクセストークンにはリフレッシュトークンが含まれません。このため、ゲームのローンチ時やユーザーがDropsのチェックを開始したときなど、折を見て[トークンを検証](https://dev.twitch.tv/docs/authentication/validate-tokens.md)していただく必要があります。

### 技術的な詳細 {#technical-details-2}

![Twitch API（オフラインインベントリ）技術詳細チャート](https://dev.twitch.tv/docs/assets/images/drops/ja/twitch-api-offline-technical-chart.png)

上記の図では、次のシステムと存在が用意されます。

* **プレイヤー** – ゲームをプレイしているユーザーです。
* **ゲーム** – あなたのゲームです。ゲーム内のインベントリシステムを除く、すべてのビジュアルおよび背景の要素を含みます。
* **ゲーム内インベントリ** – ゲームのインベントリシステム、およびプレイヤーのインベントリに変更を加えるための関連システムすべてを指します。
* **Twitch API** – TwitchのAPIです。Dropsエンタイトルメントのリストを入手し、Dropsエンタイトルメントのステータスに関する情報を更新するためにコールを行います。

### 実装 {#implementation-2}

このシステムは、ユーザーが手動で未履行のDrops報酬を確認するリクエストを送信した時点で始動します。これらのリクエストは通常、ゲーム内の設定UIの **Dropsを確認** ボタン内に表示されます。アクティベーション時に、システムはローカルに保存されたOAuthトークンを検証し、Twitch APIを呼び出して未履行のすべてのエンタイトルメントのリストを取得し、ゲームのインベントリシステムと通信し、完了後にTwitch APIを更新します。

上記の表に記載されているように、システムは以下の操作を完了する必要があります。

#### 保存されたOAuthトークンを検証する {#validate-the-stored-oauth-token}

ユーザーアクセストークンは有効期間が限られています。また、暗黙の許可フローで提供されるアクセストークンには、リフレッシュトークンは含まれません。このため、Twitch APIを呼び出す前に[トークンを検証](https://dev.twitch.tv/docs/authentication/validate-tokens.md)する必要があります。または、トークンが期限切れの場合は、APIコールを行うと **HTTP 401 Unauthorized** が返ってきます。

トークンが期限切れの場合は、そのユーザーに **Twitchに接続** ボタンでアカウントを再リンクするように伝える必要があります。

#### Twitch APIを呼び出し、エンタイトルメントのリストを取得する {#call-the-twitch-api-to-get-a-list-of-entitlements-1}

[Get Drops Entitlements API](https://dev.twitch.tv/docs/api/reference/entitlements.md#get-drops-entitlements)を使用して、ゲームの未履行エンタイトルメントすべてに関する情報を取得します。 *curl* リクエストと同様にAPIを呼び出すことができます。

```shell
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** を使用して行う必要があります。ゲームをプレイしているユーザーの情報のみが自動的に返されます。

#### 未履行のエンタイトルメントが存在することを確認する {#verify-there-are-any-unfulfilled-entitlements}

このシステムでは、ユーザーはいつでもDropsエンタイトルメントの確認を開始することができます。そのため、履行すべきDropsが存在しない可能性があります。APIの反応を通じて処理し、操作を続行する前に履行の必要があるエンタイトルメントがあることを確認してください。

#### Twitch APIを呼び出し、エンタイトルメントを履行済みとしてマークする {#call-the-twitch-api-to-mark-the-entitlements-as-fulfilled-2}

[Update Drops Entitlements API](https://dev.twitch.tv/docs/api/reference/entitlements.md#update-drops-entitlements)を使用して、エンタイトルメントが履行されたことをTwitchに通知します。この *curl* リクエストと類似のAPIを呼び出すことができます。

```shell
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"
    ]
}'
```

これはゲーム内でアイテムを付与する前でも後でも実行できますが、ゲーム内で付与する前に実行すると、インベントリシステムとの競合状態を回避できる場合があります。このコールの目的は、ユーザーがゲーム内アイテムを何度も受け取ることを防ぐことです。

トークンの期限が切れたり、インターネット接続がない場合など、APIコールが何らかの理由で失敗する場合は、プレイヤーに失敗を通知し、適切なトラブルシューティングの手順を提供する必要があります。

#### ゲーム内インベントリを更新して、報酬アイテムを含める {#update-your-in-game-inventory-to-include-the-reward-item}

このシステムは完全にゲーム内で動作するため、ゲームのインベントリを呼び出して、エンタイトルメントに関連付けられた報酬アイテムを含めることができます。

#### 報酬が付与されたことをプレイヤーに通知しましょう。 {#notify-the-player-that-the-reward-has-been-successfully-entitled}

これでプレイヤーはゲームにリダイレクトされて、受け取ったゲーム内アイテムを楽しむことができます！

## 技術的なよくある質問 {#technical-faq}

#### ユーザーのDrops受け取りを履行するために、どの程度のサポート期間が必要ですか？ {#how-long-do-i-need-to-support-fulfilling-a-drop-claim-for-a-user}

デベロッパーは、キャンペーン終了から最長で14日以内に、受け取ってアカウントをリンクする視聴者報酬を付与する必要があります。期間限定のベータ版など、時間に制約のある特定のキャンペーンでは、この要件が免除される場合があります。

#### キャンペーンが終了した後に請求が発生することはありますか？ {#can-claims-occur-after-the-campaign-ends}

はい。ユーザーがDropsを獲得するにはキャンペーン期間中に要件を満たす必要がありますが、キャンペーン終了から最大14日間までは、ユーザーがアカウントをリンクして受け取ることができます。この場合、EventSub通知を受け取り、Twitch APIによって提供されるデータが更新される場合があります。

#### EventSubおよびTwitch APIによって提供されるIDの長さに上限はありますか？ {#is-there-a-maximum-length-for-ids-provided-by-eventsub-and-twitch-api}

IDは不透明であり、変更される可能性があるため、IDの最大文字数に制限はありません。お使いのデータベースで最大文字数が要求されている場合は、柔軟性を高めるために255に設定することをお勧めします。

#### 報酬IDの形式を検証またはデコードすべきですか？ {#should-i-validate-the-format-of-or-decode-reward-ids}

いいえ。Twitch APIおよびEventSubによって提供されるDrops関連IDは不透明であり、デコードすると意味のない情報が提供されます。また、IDの形式もいつでも変更される可能性があるため、形式\( *GUIDやBase64など* \)への期待に基づいてIDを検証しないでください。

#### アカウントがリンクされる前に受け取りが行われることはありますか？ {#can-claims-happen-before-an-account-is-linked}

はい。ユーザーはアカウントをリンクする前にDrops報酬を受け取ることができます。この場合、ユーザーがアカウントをリンクするかどうか、実際にリンクを行うまで確認する必要があります。これはキャンペーンが終了してから最長14日間のみ必要なことで、それ以降はユーザーは報酬を受け取れなくなります。

#### Dropsのエンタイトルメントを「FULFILLED」としてマークする必要がありますか？ {#do-i-need-to-mark-drops-entitlements-as-fulfilled}

はい。Dropsのエンタイトルメントが正常に履行されたことを遡って確認する方法は、Twitch APIを介してそのようにマークする以外にありません。EventSubを利用するシステム内でも、キャンペーン期間中にEventSubシステムが停止して、新たなDropsエンタイトルメントを逸することがあるため、このやり方は役に立ちます。

#### APIの結果が返されるのに決まった順番はありますか？ {#is-there-an-order-to-how-api-results-are-returned}

いいえ。[Get Drops Entitlement API](https://dev.twitch.tv/docs/api/reference/entitlements.md#get-drops-entitlements)は、返される結果に決まった順番はなく、そのプロパティに関連しない順番で結果を返す可能性があります。履行状況などの特定のプロパティを持つエンタイトルメントをより適切に検索するには、APIを呼び出す際にクエリパラメータを利用します。

#### ユーザーがアカウントのリンク試行後に、アカウントリンクを表示しないのはなぜですか？ {#why-does-a-user-not-show-an-account-link-after-attempting-to-link-their-account}

Dropsキャンペーンのアカウントリンクが成功しているかどうかは、ユーザーがDrops設定内で設定され、ゲームに関連付けられたクライアントIDに対する認証を行っているかどうかで判断します。Drops設定内で設定したクライアントIDが、先述のアカウントリンクセクションで設定した「 *Twitchに接続* 」リンクと同じクライアントIDに設定されていることを確認してください。

**注意:** Dropsキャンペーンを作成後に、Drops設定内でゲームのクライアントIDを変更した場合は、新たに割り当てられたゲームのクライアントIDと同期するために、新たなキャンペーンを作成する必要があります。
