Intégrer des recommandations sur l'appareil à l'aide du SDK Engage

Ce guide explique aux développeurs comment intégrer leurs recommandations de contenus vidéo à l'aide du SDK Engage pour renseigner les expériences de recommandations sur les surfaces Google, telles que la télévision, les mobiles et les tablettes.

La recommandation exploite le cluster de recommandations pour afficher des films et des séries TV de plusieurs applications dans un même groupe d'UI. Chaque développeur partenaire peut diffuser au maximum 25 entités dans chaque cluster de recommandations, et il peut y avoir au maximum sept clusters de recommandations par requête.

Pour envoyer des recommandations non personnalisées directement depuis vos serveurs backend plutôt que depuis une appli TV, consultez Intégrer des recommandations à l'aide de l'API REST.

Travail préalable

Suivez les instructions de la section Prérequis du guide de démarrage.

  1. Exécutez la publication sur un service de premier plan.
  2. Publiez les données de recommandations au maximum une fois par jour, déclenchées par l'un des éléments suivants :
    • Première connexion de l'utilisateur de la journée. (ou)
    • Lorsque l'utilisateur commence à interagir avec l'application.

Intégration

AppEngagePublishClient publie le cluster de recommandations. Utilisez la méthode publishRecommendationClusters pour publier un objet de recommandations.

Veillez à initialiser le client et à vérifier la disponibilité du service, comme décrit dans le guide de démarrage.

client.publishRecommendationClusters(recommendationRequest)

Faire un upsert des clusters de recommandations

Les clusters sont des regroupements logiques d'entités. Les exemples de code suivants expliquent comment créer les clusters en fonction de vos préférences, comment créer une requête de publication et comment faire un upsert de tous les clusters.

RecommendationClusterType détermine la façon dont le cluster sera affiché.

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

Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :

  • Les données RecommendationsCluster existantes du développeur partenaire sont supprimées.
  • Les données de la requête sont analysées et stockées dans le cluster RecommendationsCluster mis à jour. En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

Synchronisation inter-appareil

L'option SyncAcrossDevices détermine si les données du cluster de recommandations d'un utilisateur sont partagées avec Google TV et disponibles sur ses appareils, tels que son téléviseur, son téléphone et ses tablettes. Pour que la recommandation fonctionne, elle doit être définie sur "true".

L'application multimédia doit fournir un paramètre clair pour activer ou désactiver la synchronisation entre appareils. Expliquez les avantages à l'utilisateur, stockez sa préférence une fois et appliquez-la en conséquence dans la requête publishRecommendations. Pour tirer le meilleur parti de la fonctionnalité inter-appareils, vérifiez que l'application obtient le consentement de l'utilisateur et activez SyncAcrossDevices sur true.

Supprimer les données Engage

Pour supprimer manuellement les données d'un utilisateur du serveur Google TV avant la période de conservation standard de 60 jours, utilisez la méthode client.deleteClusters(). À la réception de la requête, le service supprime toutes les données Engage existantes pour le profil du compte ou pour l'ensemble du compte.

L'énumération DeleteReason définit le motif de la suppression des données. Le code suivant supprime les recommandations lors de la déconnexion.

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

Créer des entités

Le SDK a défini différentes entités pour représenter chaque type d'élément. Les entités suivantes sont prises en charge pour le cluster "Recommandations" :

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

Fournir des descriptions

Fournissez une brève description pour chaque entité. Elle s'affichera lorsque les utilisateurs pointeront sur l'entité, leur fournissant ainsi des détails supplémentaires.

Texte d'incitation à l'action

Fournissez un texte d'incitation à l'action facultatif pour chaque entité. Ce texte sera affiché à l'utilisateur pour l'encourager à interagir.

Tags

Vous pouvez éventuellement fournir une liste de tags pour chaque entité. Les tags peuvent être utilisés pour la catégorisation et le filtrage.

URI de lecture spécifiques à la plate-forme

Créez des URI de lecture pour chaque plate-forme compatible : Android TV, Android ou iOS. Cela permet au système de sélectionner l'URI approprié pour la lecture vidéo sur la plate-forme respective.

Dans les rares cas où les URI de lecture sont identiques pour toutes les plates-formes, répétez-les pour chacune d'elles.

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

Images poster

Les images d'affiche nécessitent un URI et des dimensions en pixels (hauteur et largeur). Ciblez différents facteurs de forme en fournissant plusieurs images d'affiche, mais vérifiez que toutes les images conservent un format de 16:9 et une hauteur minimale de 200 pixels pour un affichage correct de l'entité "Recommandations", en particulier dans l'Entertainment Space de Google. Les images d'une hauteur inférieure à 200 pixels risquent de ne pas s'afficher.

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)

Motif de la recommandation

Vous pouvez éventuellement fournir un motif de recommandation que Google TV pourra utiliser pour expliquer pourquoi un film ou une série TV spécifique est suggéré à l'utilisateur.

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

Période d'affichage

Si une entité ne doit être disponible que pendant une durée limitée, définissez un délai d'expiration personnalisé. Sans date d'expiration explicite, les entités expireront automatiquement et seront effacées au bout de 60 jours. Par conséquent, ne définissez un délai d'expiration que lorsque les entités doivent expirer plus tôt. Spécifiez plusieurs créneaux de disponibilité de ce type.

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

Si vous avez intégré votre catalogue multimédia ou votre flux d'actions multimédias à Google TV, vous n'avez pas besoin de créer d'entités distinctes pour les films ou les séries TV. Vous pouvez créer un MediaActionFeedEntity qui inclut le champ obligatoire DataFeedElementId. Cet ID doit être unique et correspondre à l'ID du flux d'actions multimédias, car il permet d'identifier le contenu du flux ingéré et d'effectuer des recherches de contenu multimédia.

val id = "dataFeedElementId"

MovieEntity

Voici un exemple de création d'un MovieEntity avec tous les champs obligatoires :

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

Vous pouvez fournir des données supplémentaires telles que les genres, les classifications de contenu, la date de sortie, le motif de la recommandation et les périodes de disponibilité, qui peuvent être utilisées par Google TV pour améliorer l'affichage ou le filtrage.

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

Voici un exemple de création d'un TvShowEntity avec tous les champs obligatoires :

val tvShowEntity = TvShowEntity.Builder()
  .setName("Show title")
  .setDescription("A sentence describing TV Show.")
  .addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
  .addPosterImages(images)
  .setCallToActionText("Watch Now")
  .addTag("Drama")
  .build()

Vous pouvez éventuellement fournir des données supplémentaires telles que les genres, les classifications de contenu, le motif de la recommandation, le prix de l'offre, le nombre de saisons ou la période de disponibilité, qui peuvent être utilisées par Google TV pour améliorer l'affichage ou le filtrage.

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

Voici un exemple de création d'un MediaActionFeedEntity avec tous les champs obligatoires :

val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
  .setDataFeedElementId(id)
  .setCallToActionText("Watch Now")
  .addTag("Action")
  .build()

Vous pouvez éventuellement fournir des données supplémentaires, telles qu'une description, un motif de recommandation et une période d'affichage, qui peuvent être utilisées par Google TV pour améliorer l'affichage ou le filtrage.

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

Représente une chaîne de télévision en direct. Voici un exemple de création d'un LiveTvChannelEntity avec tous les champs obligatoires :

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

Vous pouvez éventuellement fournir des données supplémentaires, telles que des classifications de contenu ou le motif de la recommandation.

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

Représente une fiche de programme de télévision en direct diffusé ou dont la diffusion est prévue sur une chaîne de télévision en direct. Voici un exemple de création d'un LiveTvProgramEntity avec tous les champs obligatoires :

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

Vous pouvez éventuellement fournir des données supplémentaires, telles que des classifications de contenu, des genres ou le motif de la recommandation.

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