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 檔案。請妥善保管這個檔案。稍後您需要使用這個金鑰，向 API 驗證用戶端。
- Workspace 和相關聯的 Google 帳戶現在可以使用 REST API。變更生效後，系統會通知您 API 是否已可供服務帳戶呼叫。
- 請按照這些步驟，準備發出委派 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 相符。
沒有個人資料的帳戶網址為：
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster
要求的酬載會顯示在 entities 欄位中。entities 代表內容實體清單，可由下列一或多個項目組成：MovieEntity、TVEpisodeEntity、LiveStreamingVideoEntity 或 VideoClipEntity。此為必填欄位。
要求主體
欄位 |
類型 |
必要 |
說明 |
實體 |
MediaEntity 物件清單 |
是 |
內容實體清單，最多 5 個。系統只會保留前五個，其餘則會捨棄。空白清單可用來表示使用者已看完所有實體。 |
entities 欄位包含個別 movieEntity、tvEpisodeEntity、liveStreamingVideoEntity 和 videoClipEntity。
欄位 |
類型 |
說明 |
movieEntity |
MovieEntity |
代表 ContinuationCluster 中電影的物件。 |
tvEpisodeEntity |
TvEpisodeEntity |
代表 ContinuationCluster 中電視節目的物件。 |
liveStreamingVideoEntity |
LiveStreamingVideoEntity |
代表 ContinuationCluster 中直播影片的物件。 |
videoClipEntity |
VideoClipEntity |
代表 ContinuationCluster 中短片的物件。 |
實體陣列中的每個物件都必須是可用的 MediaEntity 類型之一，即 MovieEntity、TvEpisodeEntity、LiveStreamingVideoEntity 或 VideoClipEntity，以及通用和類型專屬欄位。
下列程式碼片段展示 publishContinuationCluster API 的要求主體酬載。
{
"entities": [
{
"movieEntity": {
"watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
"name": "Movie1",
"platform_specific_playback_uris": [
{
"uri": "https://www.example.com/movie_entity_uri_for_android",
"platforms": [
"PLATFORM_ANDROID_TV",
"PLATFORM_ANDROID"
]
},
{
"uri": "https://www.example.com/movie_entity_uri_for_iOS",
"platforms": [
"PLATFORM_IOS"
]
}
],
"poster_images": [
{
"url": "http://www.example.com/movie1_img1.png",
"width": 1920,
"height": 1080,
"accessibility_text": "Movie 1 HD poster"
},
{
"url": "http://www.example.com/movie1_imag2.png",
"width": 640,
"height": 360,
"accessibility_text": "Movie 1 SD poster"
}
],
"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": [
{
"uri": "https://www.example.com/episode_entity_uri_for_android_mobile",
"platforms": [
"PLATFORM_ANDROID"
]
},
{
"uri": "https://www.example.com/episode_entity_uri_for_android_tv",
"platforms": [
"PLATFORM_ANDROID_TV"
]
},
{
"uri": "https://www.example.com/episode_entity_uri_for_iOS",
"platforms": [
"PLATFORM_IOS"
]
}
],
"poster_images": [
{
"url": "http://www.example.com/episode1_img1.png",
"width": 1920,
"height": 1080,
"accessibility_text": "Episode 1 HD poster"
},
{
"url": "http://www.example.com/episode1_imag2.png",
"width": 640,
"height": 360,
"accessibility_text": "Episode 1 SD poster"
}
],
"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"
}
},
{
"liveStreamingVideoEntity": {
"name": "Live Sports Championship",
"watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
"last_engagement_time_millis": 1780978284000,
"last_play_back_position_time_millis": 1800000,
"duration_millis": 7200000,
"platform_specific_playback_uris": [
{
"uri": "https://www.example.com/live_streaming_entity_uri_for_android_tv",
"platforms": ["PLATFORM_ANDROID_TV"]
}
],
"poster_images": [
{
"url": "http://www.example.com/live_stream_image1.png",
"width": 1920,
"height": 1080,
"accessibility_text": "Live Sports Championship Cover Image"
}
],
"start_time_epoch_millis": 1780976484000,
"broadcaster": "Global Sports Network",
"broadcaster_icon": {
"url": "https://www.example.com/gsports.jpg",
"width": 512,
"height": 512,
"accessibility_text": "Global Sports Network Logo"
}
}
},
{
"videoClipEntity": {
"name": "How to Brew the Perfect Espresso",
"watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
"last_engagement_time_millis": 1780978284000,
"last_play_back_position_time_millis": 120000,
"duration_millis": 600000,
"platform_specific_playback_uris": [
{
"uri": "https://www.example.com/video_clip_entity_uri_for_android_tv",
"platforms": ["PLATFORM_ANDROID_TV"]
}
],
"poster_images": [
{
"url": "http://www.example.com/video_clip_image1.png",
"width": 1920,
"height": 1080,
"accessibility_text": "Espresso Tutorial Cover Image"
}
],
"created_time_epoch_millis": 1780900000000,
"creator": "Coffee Enthusiast John",
"creator_image": {
"url": "https://www.example.com/image/thumb/creators/john_avatar.jpg",
"width": 256,
"height": 256,
"accessibility_text": "John's Avatar"
}
}
}
]
}
刪除 Engage 資料
使用 clearCluster API 移除「參與」資料。
如要刪除接續叢集資料，請使用下列語法向 clearCluster API 執行 POST 要求。
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearCluster
其中：
package_name：：媒體供應商套件名稱。accountId：使用者帳戶在系統中的專屬 ID。必須與裝置端路徑中使用的accountId相符。profileId：使用者在系統帳戶中的設定檔專屬 ID。必須與裝置端路徑中使用的 profileId 相符。
沒有個人資料的帳戶網址為：
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/clearCluster
clearCluster API 的酬載只包含一個欄位 reason，其中包含 DeleteReason，用於指定移除資料的原因。
{
"reason": "DELETE_REASON_LOSS_OF_CONSENT"
}
測試
成功發布資料後，請使用使用者測試帳戶，確認預期內容會顯示在目標 Google 介面的「繼續觀看」列中，例如 Google TV，以及 Android 和 iOS 版 Google TV 行動應用程式。
測試時，請預留幾分鐘的合理傳播延遲時間，並遵守觀看規定，例如觀看部分電影或看完一集。詳情請參閱應用程式開發人員適用的「接著看」指南。