Contents

Drops技術ガイド

目次

はじめに

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

組織とゲームの所有権

Dropsキャンペーンを作成する前に、Dropsキャンペーンの作成を希望するゲームカテゴリーの所有権を現在保持している デベロッパー組織 が必要です。そのような組織がすでに存在するかどうかは会社に確認してください。存在しない場合、組織の作成方法については、組織の登録および管理をご覧ください。

組織にゲームが割り当てられていない場合は、ゲームの所有権を要求する必要があります。Twitchであなたのゲームカテゴリーの所有権をリクエストする方法については、ゲーム管理をご覧ください。

手続きを続行するには、組織とゲームの所有権の両方が承認されるのを待つ必要があります。これらのリクエストを行ったばかりなら、承認されるまでに1～2週間かかる場合があります。組織のリクエストが拒否されるという問題がよくあるのですが、これを避けるために、組織リクエストが拒否された理由をご覧ください。

アカウントのリンク

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

クライアントIDの取得

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

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

アカウントリンクプロセスの設定

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

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

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

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

クライアントIDに対するユーザーの認証の詳細については、Twitch OAuthガイドをご覧ください。Dropsの認証方法として最も一般的なのは Implicit Grant Flowと Authorization Code Grant Flowです。これらの手順で使用するクライアントIDは、このページで前述したクライアントID でなければなりません 。そうでない場合、アカウントリンクの手順が機能しません。

アカウントのリンク解除の取り扱いについて

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

いずれの場合でも、あなたのクライアントIDに付与されたユーザーの認証が取り消されたかまたは削除されたことが理由となります。ユーザーがアカウントを接続解除したかどうかを確認するには、OAuthトークンの有効性を確認します。

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

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

アカウントリンクの削除

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

セキュリティ上の理由から、OAuthアクセストークンを取り消すことをおすすめします。ユーザーのTwitchアカウントから、アカウントリンクが表示されないようにする方法はありません。ユーザーがアカウントに再リンクしたい場合は、Twitch上のリンクを手動で削除する必要があります。

Dropsシステムの設計

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

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

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

EventSub + Twitch API

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

技術的な詳細

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

EventSub + Twitch API技術詳細チャート

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

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

EventSubの設定

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

EventSubサブスクタイプ

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

EventSubトピックにサブスクライブするには、イベントへのサブスクライブの手順に従ってください。この特定のサブスクタイプでは、条件内にorganization_idを含める必要があります。また、任意でcategory_idとcampaign_idを含めることもできます。ほとんどの場合は、organization_idを定義するだけで済みます。他の定義はこれらのフィールドでフィルタリングされたDrops通知を提供するのみです。

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

実装

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

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

Dropsエンタイトルメントの付与を承諾する

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

[
    {
        "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通知に複数のユーザーがリストされる可能性があります。ペイロードの配列内のすべてのエンタイトルメントをスキャンし、どのエンタイトルメントがどのユーザーに付与されるのかを一時的に保存する必要があります。

あなたのデータベースからユーザー情報を取得

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

ユーザーがデータベース内に存在しない場合は、そのユーザーはまだアカウントをリンクしていません。この時点では通知を無視して、あとで処理する必要があります。あなたはキャンペーン終了から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"
    ]
}'

このAPIコールは複数のユーザーに影響を与える可能性があるため、App Access Tokenを使用してコールを行う必要があります。ペイロードレスポンスの例など、このAPIの詳細については、Update Drops Entitlements APIを参照してください。

最後に

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

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

Twitch API (ホストされたインベントリ)

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

技術的な詳細

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

Twitch API (ホストされたインベントリ) 技術詳細表

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

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

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

実装

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

アクティベーションが完了すると、システムは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 を使用している場合、クエリパラメーターでuser_idを特別に指定しない限り、APIはすべてのユーザーのエンタイトルメントを返します。

あなたのデータベースからユーザー情報を取得

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

ユーザーがデータベース内に存在しない場合は、そのユーザーはまだアカウントをリンクしていません。この時点では通知を無視して、あとで処理する必要があります。あなたはキャンペーン終了から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 を使用している場合は、このAPIコールを使用して、クライアントIDの所有者がメンバーになっている組織が所有するゲームに関連付けられたエンタイトルメントを変更できます。

最後に

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

Twitch API (オフラインインベントリ)

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

アカウントのリンク

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

Twitch API (オフラインインベントリ) アカウントリンクチャート

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

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

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

技術的な詳細

Twitch API（オフラインインベントリ）技術詳細チャート

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

実装

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

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

保存されたOAuthトークンを検証する

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

トークンが期限切れの場合は、そのユーザーに 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 を使用して行う必要があります。ゲームをプレイしているユーザーの情報のみが自動的に返されます。

未履行のエンタイトルメントが存在することを確認する

このシステムでは、ユーザーはいつでもDropsエンタイトルメントの確認を開始することができます。そのため、履行すべきDropsが存在しない可能性があります。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"
    ]
}'

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

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

ゲーム内インベントリを更新して、報酬アイテムを含める

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

報酬が付与されたことをプレイヤーに通知しましょう。

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

技術的なよくある質問

ユーザーのDrops受け取りを履行するために、どの程度のサポート期間が必要ですか？

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

キャンペーンが終了した後に請求が発生することはありますか？

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

EventSubおよびTwitch APIによって提供されるIDの長さに上限はありますか？

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

報酬IDの形式を検証またはデコードすべきですか？

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

アカウントがリンクされる前に受け取りが行われることはありますか？

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

Dropsのエンタイトルメントを「FULFILLED」としてマークする必要がありますか？

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

APIの結果が返されるのに決まった順番はありますか？

いいえ。Get Drops Entitlement APIは、返される結果に決まった順番はなく、そのプロパティに関連しない順番で結果を返す可能性があります。履行状況などの特定のプロパティを持つエンタイトルメントをより適切に検索するには、APIを呼び出す際にクエリパラメータを利用します。

ユーザーがアカウントのリンク試行後に、アカウントリンクを表示しないのはなぜですか？

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

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

Docs Status Support Showcase Blog