本指南提供操作說明,協助開發人員使用 Engage SDK 整合推薦影片內容,在電視、手機和平板電腦等 Google 途徑中,提供推薦內容體驗。
推薦功能會利用推薦叢集,在一個 UI 群組中顯示多個應用程式的電影和電視節目。每個開發合作夥伴最多可在每個推薦叢集中播送 25 個實體,且每項要求最多可有 7 個推薦叢集。
如要直接從後端伺服器 (而非 TV 應用程式) 傳送非個人化推薦內容,請參閱「使用 REST API 整合推薦內容」。
事前作業
完成入門指南中的事前準備操作說明。
- 在前景服務上執行發布作業。
- 每天最多發布一次推薦內容資料,觸發條件為下列任一事件:
- 使用者當天首次登入。(或)
- 使用者開始與應用程式互動時。
整合
AppEngagePublishClient 會發布推薦叢集。使用 publishRecommendationClusters 方法發布建議物件。
請務必按照入門指南所述,初始化用戶端並檢查服務可用性。
client.publishRecommendationClusters(recommendationRequest)
更新插入推薦叢集
叢集是實體的邏輯群組。下列程式碼範例說明如何根據偏好設定建立叢集,以及如何建立發布要求和 upsert 所有叢集。
RecommendationClusterType 決定叢集的顯示方式。
// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
.Builder()
.addEntity(movie1)
.addEntity(movie2)
.addEntity(movie3)
.addEntity(movie4)
.addEntity(tvShow)
// This cluster is meant to be used as an individual provider row
.setRecommendationClusterType(TYPE_PROVIDER_ROW)
.setTitle("Popular Movies")
.build()
// cluster for live TV programs
val recommendationCluster2 = RecommendationCluster
.Builder()
.addEntity(liveTvProgramEntity1)
.addEntity(liveTvProgramEntity2)
.addEntity(liveTvProgramEntity3)
.addEntity(liveTvProgramEntity4)
.addEntity(liveTvProgramEntity5)
// This cluster is meant to be used as an individual provider row
.setRecommendationClusterType(TYPE_PROVIDER_ROW)
.setTitle("Popular Live TV Programs")
.build()
// creating a publishing request
val recommendationRequest = PublishRecommendationClustersRequest
.Builder()
.setSyncAcrossDevices(true)
.setAccountProfile(accountProfile)
.addRecommendationCluster(recommendationCluster1)
.addRecommendationCluster(recommendationCluster2)
.build()
服務收到要求後,系統會在單一交易中執行以下動作:
- 移除開發合作夥伴提供的現有
RecommendationsCluster資料。 - 剖析要求所提供的資料並儲存在更新後的
RecommendationsCluster。如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
跨裝置同步
SyncAcrossDevices 旗標可控制是否要與 Google TV 共用使用者的推薦內容叢集資料,並在電視、手機、平板電腦等裝置上提供。如要讓建議生效,請務必將這個值設為 true。
取得同意聲明
媒體應用程式必須提供明確的設定,讓使用者啟用或停用跨裝置同步功能。向使用者說明好處,並儲存使用者的偏好設定,然後在 publishRecommendations 要求中套用。為充分發揮跨裝置功能,請確認應用程式已取得使用者同意,並啟用 SyncAcrossDevices 至 true。
刪除 Engage 資料
如要在標準 60 天保留期限前,手動刪除 Google TV 伺服器中的使用者資料,請使用 client.deleteClusters() 方法。服務收到要求後,會刪除帳戶設定檔或整個帳戶的所有現有 Engage 資料。
DeleteReason 列舉會定義刪除資料的原因。下列程式碼會在登出時移除推薦內容。
// If the user logs out from your media app, you must make the following call
// to remove recommendations data from the current Google TV device, otherwise,
// the recommendations data persists on the current Google TV device until 60
// days later.
client.deleteClusters(
DeleteClustersRequest.Builder()
.setAccountProfile(accountProfile)
.setDeleteReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
.build()
)
// If the user revokes the consent to share data with Google TV, you must make
// the following call to remove recommendations data from all current Google TV
// devices. Otherwise, the recommendations data persists until 60 days later.
client.deleteClusters(
DeleteClustersRequest.Builder()
.setAccountProfile(accountProfile)
.setDeleteReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
.build()
)
建立實體
SDK 定義了不同實體,用來代表各種項目類型。推薦叢集支援下列實體:
提供說明
為每個實體提供簡短說明。當使用者將滑鼠游標懸停在實體上時,系統會顯示這段說明,提供更多詳細資料。
行動號召文字
為每個實體提供選用的行動號召文字。這段文字會向使用者顯示,鼓勵他們參與。
標記
您可以選擇為每個實體提供標記清單。標記可用於分類和篩選。
平台專屬播放 URI
為每個支援的平台 (Android TV、Android 或 iOS) 建立播放 URI。這樣系統才能選取適當的 URI,在對應的平台上播放影片。
在極少數情況下,如果所有平台的播放 URI 都相同,請為每個平台重複這個步驟。
// Required. Set this when you want recommended entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_ANDROID_TV)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
.build()
// Optional. Set this when you want recommended entities to show up on
// Google TV Android app
val playbackUriAndroid = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
.build()
// Optional. Set this when you want recommended entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_IOS)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
.build()
val platformSpecificPlaybackUris =
Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)
// Provide appropriate rating for the system.
val contentRating = RatingSystem
.Builder()
.setAgencyName("MPAA")
.setRating("PG-13")
.build()
代表圖片
海報圖片需要 URI 和像素尺寸 (高度和寬度)。提供多張海報圖片,指定不同的板型規格,但請確認所有圖片都維持 16:9 的顯示比例,且高度至少為 200 像素,才能正確顯示「推薦」實體,尤其是在 Google 的娛樂空間中。高度小於 200 像素的圖片可能無法顯示。
val image1 = Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
.setImageHeightInPixel(300)
.setImageWidthInPixel(169)
.build()
val image2 = Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image2.png"))
.setImageHeightInPixel(640)
.setImageWidthInPixel(360)
.build()
// And other images for different form factors.
val images = Arrays.asList(image1, image2)
建議原因
您可以選擇提供推薦原因,Google TV 可用來建構原因,向使用者建議特定電影或電視節目。
//Allows us to construct reason: "Because it is top 10 on your Channel"
val topOnPartner = RecommendationReasonTopOnPartner
.Builder()
.setNum(10) //any valid integer value
.build()
//Allows us to construct reason: "Because it is popular on your Channel"
val popularOnPartner = RecommendationReasonPopularOnPartner
.Builder()
.build()
//Allows us to construct reason: "New to your channel, or Just added"
val newOnPartner = RecommendationReasonNewOnPartner
.Builder()
.build()
//Allows us to construct reason: "Because you watched Star Wars"
val watchedSimilarTitles = RecommendationReasonWatchedSimilarTitles
.Builder()
.addSimilarWatchedTitleName("Movie or TV Show Title")
.addSimilarWatchedTitleName("Movie or TV Show Title")
.build()
//Allows us to construct reason: "Recommended for you by ChannelName"
val recommendedForUser = RecommendationReasonRecommendedForUser
.Builder()
.build()
val watchAgain = RecommendationReasonWatchAgain
.Builder()
.build()
val fromUserWatchList = RecommendationReasonFromUserWatchlist
.Builder()
.build()
val userLikedTitle = RecommendationReasonUserLikedTitle
.Builder()
.setLikedTitleName("Movie or TV Show Title")
.build()
val generic = RecommendationReasonGeneric.Builder().build()
顯示時間範圍
如果實體僅限在特定時間內使用,請設定自訂到期時間。如果未明確指定到期時間,實體會在 60 天後自動到期並清除。因此,只有在實體需要提早到期時,才設定到期時間。指定多個這類播映時段。
val window1 = DisplayTimeWindow
.Builder()
.setStartTimestampMillis(now() + 1.days.toMillis())
.setEndTimestampMillis(now() + 30.days.toMillis())
.build()
val window2 = DisplayTimeWindow
.Builder()
.setEndTimestampMillis(now() + 30.days.toMillis())
.build()
val availabilityTimeWindows: List<DisplayTimeWindow> = listOf(window1, window2)
DataFeedElementId
如果您已將媒體目錄或媒體動作動態饋給與 Google TV 整合,則不必為電影或電視節目建立個別實體,而是可以建立包含必要欄位 DataFeedElementId 的 MediaActionFeedEntity。這個 ID 必須不重複,且與媒體動作動態饋給中的 ID 相符,因為這有助於識別擷取的動態饋給內容,以及執行媒體內容查詢。
val id = "dataFeedElementId"
MovieEntity
以下範例說明如何建立包含所有必填欄位的 MovieEntity:
val movieEntity = MovieEntity.Builder()
.setName("Movie name")
.setDescription("A sentence describing movie.")
.addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
.addPosterImages(images)
// Suppose the duration is 2 hours, it is 72000000 in milliseconds
.setDurationMillis(72000000)
.setCallToActionText("Watch Now")
.addTag("Action")
.build()
您可以提供其他資料,例如類型、內容分級、推出日期、推薦原因和供應時間範圍,Google TV 可能會使用這些資料來強化顯示或篩選。
val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("pg-13").build()
val contentRatings = Arrays.asList(rating1)
//Suppose release date is 11-02-2025
val releaseDate = 1739233800000L
val movieEntity = MovieEntity.Builder()
...
.addGenres(genres)
.setReleaseDateEpochMillis(releaseDate)
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addAllAvailabilityTimeWindows(availabilityTimeWindows)
.build()
TvShowEntity
以下範例說明如何建立包含所有必填欄位的 TvShowEntity:
val tvShowEntity = TvShowEntity.Builder()
.setName("Show title")
.setDescription("A sentence describing TV Show.")
.addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
.addPosterImages(images)
.setCallToActionText("Watch Now")
.addTag("Drama")
.build()
您也可以選擇提供其他資料,例如類型、內容分級、推薦原因、優惠價格、季數或供應時間範圍,Google TV 可能會使用這些資料來強化顯示或篩選。
val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder()
.setAgencyName("MPAA")
.setRating("pg-13")
.build()
val price = Price.Builder()
.setCurrentPrice("$14.99")
.setStrikethroughPrice("$16.99")
.build()
val contentRatings = Arrays.asList(rating1)
val seasonCount = 5
val tvShowEntity = TvShowEntity.Builder()
...
.addGenres(genres)
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addAllAvailabilityTimeWindows(availabilityTimeWindows)
.setSeasonCount(seasonCount)
.setPrice(price)
.build()
MediaActionFeedEntity
以下舉例說明如何建立包含所有必要欄位的 MediaActionFeedEntity:
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setDataFeedElementId(id)
.setCallToActionText("Watch Now")
.addTag("Action")
.build()
您可以視需要提供其他資料,例如說明、推薦原因和顯示時間範圍,Google TV 可能會使用這些資料來強化顯示效果或進行篩選。
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setName("Movie name or TV Show name")
.setDescription("A sentence describing an entity")
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addPosterImages(images)
.build()
LiveTvChannelEntity
這代表電視直播頻道。以下範例說明如何建立包含所有必要欄位的 LiveTvChannelEntity:
val liveTvChannelEntity = LiveTvChannelEntity.Builder()
.setName("Channel Name")
// ID of the live TV channel
.setEntityId("https://www.example.com/channel/12345")
.setDescription("A sentence describing this live TV channel.")
// channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
.addPlatformSpecificPlaybackUris(channelPlaybackUris)
.setLogoImage(logoImage)
.setCallToActionText("Watch Now")
.addTag("News")
.build()
您可以視需要提供其他資料,例如內容分級或推薦原因。
val rating1 = RatingSystem.Builder()
.setAgencyName("MPAA")
.setRating("pg-13")
.build()
val contentRatings = Arrays.asList(rating1)
val liveTvChannelEntity = LiveTvChannelEntity.Builder()
...
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner)
.build()
LiveTvProgramEntity
這代表正在或預定在電視直播頻道播出的電視直播節目資訊卡。以下舉例說明如何建立包含所有必填欄位的 LiveTvProgramEntity:
val liveTvProgramEntity = LiveTvProgramEntity.Builder()
// First set the channel information
.setChannelName("Channel Name")
.setChannelId("https://www.example.com/channel/12345")
// channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
.addPlatformSpecificPlaybackUris(channelPlaybackUris)
.setChannelLogoImage(channelLogoImage)
// Then set the program or card specific information.
.setName("Program Name")
.setEntityId("https://www.example.com/schedule/123")
.setDescription("Program Description")
.addAvailabilityTimeWindow(
DisplayTimeWindow.Builder()
.setStartTimestampMillis(1756713600000L) // 2025-09-01T07:30:00+0000
.setEndTimestampMillis(1756715400000L) // 2025-09-01T08:00:00+0000
.build()
)
.addPosterImage(programImage)
.setCallToActionText("Watch Now")
.addTag("Sports")
.build()
視需要提供其他資料,例如內容分級、類型或推薦原因。
val rating1 = RatingSystem.Builder()
.setAgencyName("MPAA")
.setRating("pg-13")
.build()
val contentRatings = Arrays.asList(rating1)
val genres = Arrays.asList("Action", "Science fiction")
val liveTvProgramEntity = LiveTvProgramEntity.Builder()
...
.addContentRatings(contentRatings)
.addGenres(genres)
.setRecommendationReason(topOnPartner)
.build()