使用 Engage SDK 在设备上集成推荐内容

本指南包含面向开发者的说明,介绍了如何使用 Engage SDK 集成推荐视频内容,以便在各种 Google 途径(例如电视、手机和平板电脑)中填充推荐体验。

推荐功能利用推荐集群在一个界面分组中显示来自多个应用的影视内容。每个开发者合作伙伴最多可以在每个推荐集群中广播 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 都相同,请为每个平台重复该 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

如果您已将媒体目录或媒体操作 Feed 与 Google TV 集成,则无需为电影或电视节目创建单独的实体,而是可以创建一个包含必填字段 DataFeedElementId 的 MediaActionFeedEntity。此 ID 必须是唯一的,并且必须与媒体操作 Feed 中的 ID 一致,因为它有助于识别提取的 Feed 内容并执行媒体内容查找。

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()