Engage SDK を使用してオンデバイスでレコメンデーションを統合する

このガイドでは、Engage SDK を使用しておすすめの動画コンテンツを統合し、テレビ、モバイル、タブレットなどの Google サーフェス全体におすすめを表示する手順を説明します。

おすすめコンテンツは、おすすめコンテンツ クラスタを利用して、複数のアプリの映画やテレビ番組を 1 つの UI グループに表示します。各デベロッパー パートナーは、各おすすめクラスタで最大 25 個のエンティティをブロードキャストできます。また、リクエストごとにおすすめクラスタを最大 7 個含めることができます。

TV アプリからではなく、バックエンド サーバーから直接パーソナライズされていないおすすめを送信するには、REST API を使用しておすすめを統合するをご覧ください。

事前作業

スタートガイドの事前準備の手順を完了します。

  1. フォアグラウンド サービスでパブリッシュを実行する。
  2. 次のいずれかをトリガーとして、1 日に 1 回、レコメンデーション データを公開します。
    • ユーザーのその日の最初のログイン。(または)
    • ユーザーがアプリの操作を開始したとき。

統合

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

サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。

  • デベロッパー パートナーが提供した既存の 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 とピクセル単位のサイズ(高さと幅)が必要です。複数のポスター画像を提供することで、さまざまなフォーム ファクタをターゲットに設定できます。ただし、特に Google のエンターテイメント スペース内で「おすすめ」エンティティが正しく表示されるように、すべての画像のアスペクト比が 16:9 で、高さが 200 ピクセル以上であることを確認してください。高さが 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()