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

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

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

前提条件

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

アクセス権を取得する

Google Cloud コンソールで API を表示して有効にするには、アカウントを登録する必要があります。

Google Workspace お客様 ID が利用可能である必要があります。利用できない場合は、Google Workspace と、API の呼び出しに使用する Google アカウントを設定する必要があります。
Google Workspace に関連付けられているメールアドレスを使用して、Google Cloud コンソールでアカウントを設定します。
新しいプロジェクトを作成します。
API 認証用のサービスアカウントを作成します。サービスアカウントを作成すると、次の 2 つの項目が作成されます。
- サービスアカウント ID。
- サービスアカウントキーを含む JSON ファイル。このファイルは安全な場所に保管してください。これは、後で API に対してクライアントを認証するために必要になります。
ワークスペースと関連付けられた Google アカウントで REST API を使用できるようになりました。変更が伝播されると、サービスアカウントから API を呼び出す準備ができたかどうかを通知します。
委任された API 呼び出しを行う準備を行うには、こちらの手順に沿って操作します。

継続クラスタを公開する

動画検出データを公開するには、次の構文を使用して 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 のいずれかであるコンテンツエンティティのリストを表します。これは必須項目です。

リクエストの本文

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

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

フィールド	文字入力	必須	説明
movieEntity	MovieEntity	はい	ContinuationCluster 内の映画を表すオブジェクト。
tvEpisodeEntity	TvEpisodeEntity	はい	ContinuationCluster 内のテレビエピソードを表すオブジェクト。

entities 配列内の各オブジェクトは、共通フィールドとタイプ固有のフィールドとともに、利用可能な 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"
      }
    }
  ]
}

動画の検出データを削除する

clearClusters API を使用して、動画検出データを削除します。

継続クラスタのデータを削除するには、次の構文を使用して 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 のペイロードには 1 つのフィールド（reason）のみが含まれます。このフィールドには、データを削除する理由を指定する DeleteReason が含まれます。

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

テスト

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

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