使用 Engage SDK 在裝置端整合推薦內容

本指南提供操作說明,協助開發人員使用 Engage SDK 整合推薦影片內容,在電視、手機和平板電腦等 Google 途徑中,提供推薦內容體驗。

推薦功能會利用推薦叢集,在一個 UI 群組中顯示多個應用程式的電影和電視節目。每個開發合作夥伴最多可在每個推薦叢集中播送 25 個實體,且每項要求最多可有 7 個推薦叢集。

如要直接從後端伺服器 (而非 TV 應用程式) 傳送非個人化推薦內容,請參閱「使用 REST API 整合推薦內容」。

事前作業

完成入門指南中的事前準備操作說明。

  1. 在前景服務上執行發布作業。
  2. 每天最多發布一次推薦內容資料,觸發條件為下列任一事件:
    • 使用者當天首次登入。(或)
    • 使用者開始與應用程式互動時。

整合

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 定義了不同實體,用來代表各種項目類型。推薦叢集支援下列實體:

  1. MediaActionFeedEntity
  2. MovieEntity
  3. TvShowEntity
  4. LiveTvChannelEntity
  5. LiveTvProgramEntity

提供說明

為每個實體提供簡短說明。當使用者將滑鼠游標懸停在實體上時,系統會顯示這段說明,提供更多詳細資料。

行動號召文字

為每個實體提供選用的行動號召文字。這段文字會向使用者顯示,鼓勵他們參與。

標記

您可以選擇為每個實體提供標記清單。標記可用於分類和篩選。

平台專屬播放 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()