REST API を使用して「続きを見る」を統合する

Engage SDK は、iOS や Roku TV などの Android 以外のプラットフォームで、一貫した続きを見る視聴体験を提供するための REST API を提供します。デベロッパーは、この API を使用して、Android 以外のプラットフォームからオプトインしたユーザーの [続きを見る] ステータスを更新できます。

前提条件

**重要:** Engage を使用した開発に関心があることを表明してください。

• まず、デバイス上の Engage SDK ベースの 統合を完了する必要があります。この重要なステップでは、Google のユーザー ID とアプリの AccountProfile の間に必要な関連付けを確立します。
• API アクセスと認証: Google Cloud プロジェクトで API を表示して有効にするには、許可リスト登録プロセスを行う必要があります。すべての API リクエストで認証が必要です。

アクセス権を取得する

Google Cloud コンソールで API を表示して有効にするためのアクセス権を取得するには、アカウントを登録する必要があります。

1. Google Workspace お客様 ID が必要です。お客様 ID がない場合は、Google Workspace と、API の呼び出しに使用する Google アカウントを設定する必要があります。
2. Google Workspace に関連付けられたメールを使用して、Google Cloud コンソールでアカウントを設定します。
3. 新しいプロジェクトを作成します。
4. API 認証用のサービス アカウントを作成します。サービス アカウントを作成すると、次の 2 つのアイテムが作成されます。
   • サービス アカウント ID。
   • サービス アカウント キーを含む JSON ファイル。このファイルは安全に保管してください。後でクライアントを API に対して認証するために必要になります。
5. Workspace と関連付けられた Google アカウントで REST API を使用できるようになりました。 変更が反映されると、サービス アカウントで API を呼び出す準備ができたかどうか通知されます。
6. 委任された API 呼び出しを行う準備として、次の手順を行います。

継続クラスタを公開する

Engage データを公開するには、次の構文を使用して publishContinuationCluster API に POST リクエストを発行します。

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

ここで

• package_name: メディア プロバイダのパッケージ名
• accountId: システム内のユーザー アカウントの一意の ID。デバイス上のパスで使用されている accountId と一致する必要があります。
• profileId: システム内のアカウント内のユーザー プロファイルの一意の ID。デバイス上のパスで使用されている profileId と一致する必要があります。

プロファイルのないアカウントの URL は次のとおりです。

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

リクエストのペイロードは entities フィールドで表されます。entities はコンテンツ エンティティのリストを表します。これは MovieEntity または TVEpisodeEntity のいずれかになります。これは必須項目です。

リクエストの本文

フィールド	型	必須	説明
エンティティ	MediaEntity オブジェクトのリスト	はい	コンテンツ エンティティのリスト（最大 5 個）。上位 5 つのみが 保持され、残りは削除されます。空のリストを指定すると、ユーザーがすべてのエンティティの視聴を完了したことを示します。

フィールド entities には、個々の movieEntity と tvEpisodeEntity が含まれます。

フィールド	型	必須	説明
movieEntity	MovieEntity	はい	ContinuationCluster 内の映画を表すオブジェクト。
tvEpisodeEntity	TVEpisodeEntity	はい	ContinuationCluster 内のテレビ番組のエピソードを表すオブジェクト。

エンティティ配列内の各オブジェクトは、使用可能な MediaEntity 型 （MovieEntity と TvEpisodeEntity）のいずれかである必要があります。また、共通フィールドと型固有の フィールドも必要です。

次のコード スニペットは、publishContinuationCluster API のリクエスト本文のペイロードを示しています。

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/movie1_img1.png",
          "http://www.example.com/movie1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/episode1_img1.png",
          "http://www.example.com/episode1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    }
  ]
}

Engage データを削除する

clearClusters API を使用して、Engage データを削除します。

継続クラスタデータを削除するには、次の構文を使用して clearClusters API に POST リクエストを発行します。

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearClusters

ここで

• package_name: メディア プロバイダのパッケージ名。
• accountId: システム内のユーザー アカウントの一意の ID。デバイス上のパスで使用されている accountId と一致する必要があります。
• profileId: システム内のアカウント内のユーザー プロファイルの一意の ID。デバイス上のパスで使用されている profileId と一致する必要があります。

clearClusters API のペイロードには、reason という 1 つのフィールドのみが含まれます。このフィールドには、データを削除する理由を指定する DeleteReason が含まれます。

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

テスト

データの投稿が成功したら、ユーザー テスト アカウントを使用して、Google TV、Android と iOS の Google TV モバイルアプリなどのターゲット Google サーフェスの [続きを見る] 行に、想定されるコンテンツが表示されることを確認します。

テストでは、数分の適切な伝播遅延を許容し、映画の一部を視聴する、エピソードを最後まで視聴するなど、視聴要件を満たしてください。詳しくは、アプリ デベロッパー向け Watch Next ガイドラインをご覧ください 。