使用 REST API 整合「繼續觀看」功能

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

Engage SDK 提供 REST API，可在 iOS 和 Roku TV 等非 Android 平台上，提供一致的「繼續觀看」體驗。開發人員可透過這項 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 驗證的服務帳戶。建立服務帳戶後，您會取得兩項資訊：
- 服務帳戶 ID。
- 內含服務帳戶金鑰的 JSON 檔案。請妥善保管這個檔案。您之後需要這個 ID，才能向 API 驗證用戶端。
Workspace 和相關聯的 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 相符。

沒有個人資料的帳戶網址為：

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

要求酬載會以 entities 欄位表示。entities 代表內容實體清單，可以是 MovieEntity 或 TVEpisodeEntity。此為必填欄位。

要求主體

欄位	類型	必要	說明
實體	MediaEntity 物件清單	是	最多 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"
      }
    }
  ]
}

刪除影片探索資料

使用 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 的酬載只包含一個欄位 reason，其中包含 DeleteReason，指定移除資料的原因。

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

測試

成功發布資料後，請使用使用者測試帳戶，確認預期內容會顯示在目標 Google 服務 (例如 Google TV、Android 和 iOS 版 Google TV 行動應用程式) 的「繼續觀看」列中。

在測試中，請允許合理的傳播延遲 (幾分鐘)，並遵守觀看規定，例如觀看部分電影或看完一集節目。詳情請參閱應用程式開發人員適用的「接下來請觀看」指南。