Integra i contenuti consigliati sul dispositivo utilizzando l'SDK Engage

Questa guida contiene istruzioni per gli sviluppatori su come integrare i contenuti video consigliati, utilizzando l'SDK Engage, per compilare le esperienze di contenuti consigliati sulle piattaforme Google, come TV, dispositivi mobili e tablet.

I contenuti consigliati sfruttano il cluster dei contenuti consigliati per mostrare film e programmi TV di più app in un unico raggruppamento della UI. Ogni partner sviluppatore può trasmettere un massimo di 25 entità in ogni cluster di contenuti consigliati e può esserci un massimo di 7 cluster di contenuti consigliati per richiesta.

Per inviare consigli non personalizzati direttamente dai server di backend anziché da un'app TV, consulta Integra i consigli utilizzando l'API REST.

Preparazione

Completa le istruzioni della sezione Attività preliminari della guida introduttiva.

  1. Esegui la pubblicazione su un servizio in primo piano.
  2. Pubblica i dati dei suggerimenti al massimo una volta al giorno, attivati da uno dei seguenti eventi:
    • Primo accesso dell'utente della giornata. (or)
    • Quando l'utente inizia a interagire con l'applicazione.

Integrazione

AppEngagePublishClient pubblica il cluster di suggerimenti. Utilizza il metodo publishRecommendationClusters per pubblicare un oggetto dei suggerimenti.

Assicurati di inizializzare il client e di verificare la disponibilità del servizio come descritto nella Guida introduttiva.

client.publishRecommendationClusters(recommendationRequest)

Applicazione dell'upsert ai cluster di suggerimenti

I cluster sono raggruppamenti logici delle entità. Gli esempi di codice riportati di seguito spiegano come creare i cluster in base alle tue preferenze e come creare una richiesta di pubblicazione e applicare l'upsert a tutti i cluster.

RecommendationClusterType determina il modo in cui verrà visualizzato il cluster.

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

Quando il servizio riceve la richiesta, all'interno di una transazione vengono eseguite le seguenti azioni:

  • I dati RecommendationsCluster esistenti del partner sviluppatore vengono rimossi.
  • I dati della richiesta vengono analizzati e archiviati nel RecommendationsCluster aggiornato. In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

Sincronizzazione cross-device

Il flag SyncAcrossDevices controlla se i dati del cluster di contenuti consigliati di un utente vengono condivisi con Google TV e resi disponibili sui suoi dispositivi, come TV, smartphone e tablet. Affinché il suggerimento funzioni, deve essere impostato su true.

L'applicazione multimediale deve fornire un'impostazione chiara per attivare o disattivare la sincronizzazione tra dispositivi. Spiega i vantaggi all'utente, memorizza la sua preferenza una sola volta e applicala di conseguenza nella richiesta publishRecommendations. Per sfruttare al meglio la funzionalità cross-device, verifica che l'app ottenga il consenso dell'utente e attivi SyncAcrossDevices su true.

Elimina i dati di Engage

Per eliminare manualmente i dati di un utente dal server di Google TV prima del periodo di conservazione standard di 60 giorni, utilizza il metodo client.deleteClusters(). Alla ricezione della richiesta, il servizio elimina tutti i dati di Engage esistenti per il profilo dell'account o per l'intero account.

L'enum DeleteReason definisce il motivo dell'eliminazione dei dati. Il seguente codice rimuove i contenuti consigliati al momento della disconnessione.

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

Crea entità

L'SDK ha definito entità diverse per rappresentare ogni tipo di articolo. Per il cluster dei suggerimenti sono supportate le seguenti entità:

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

Fornisci descrizioni

Fornisci una breve descrizione per ogni entità. Questa descrizione verrà visualizzata quando gli utenti passano il mouse sopra l'entità, fornendo loro ulteriori dettagli.

Call to action text

Fornisci un testo facoltativo per la call to action di ogni entità. Questo testo verrà mostrato all'utente per incoraggiare il coinvolgimento.

Tag

Facoltativamente, fornisci un elenco di tag per ogni entità. I tag possono essere utilizzati per la categorizzazione e l'applicazione di filtri.

URI di riproduzione specifici per la piattaforma

Crea URI di riproduzione per ogni piattaforma supportata: Android TV, Android o iOS. In questo modo, il sistema può selezionare l'URI appropriato per la riproduzione dei video sulla rispettiva piattaforma.

Nel raro caso in cui gli URI di riproduzione siano identici per tutte le piattaforme, ripetili per ogni piattaforma.

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

Immagini del poster

Le immagini poster richiedono un URI e dimensioni in pixel (altezza e larghezza). Scegli come target diversi fattori di forma fornendo più immagini poster, ma verifica che tutte le immagini mantengano proporzioni di 16:9 e un'altezza minima di 200 pixel per la visualizzazione corretta dell'entità "Contenuti consigliati", in particolare all'interno di Entertainment Space di Google. Le immagini con un'altezza inferiore a 200 pixel potrebbero non essere visualizzate.

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)

Motivo del consiglio

Facoltativamente, fornisci un motivo per il suggerimento che può essere utilizzato da Google TV per creare i motivi per cui suggerire un film o un programma TV specifico all'utente.

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

Finestra temporale di visualizzazione

Se un'entità deve essere disponibile solo per un periodo di tempo limitato, imposta una data di scadenza personalizzata. Senza una data di scadenza esplicita, le entità scadranno automaticamente e verranno cancellate dopo 60 giorni. Quindi, imposta un'ora di scadenza solo quando le entità devono scadere prima. Specifica più finestre di disponibilità di questo tipo.

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

Se hai integrato il tuo catalogo multimediale o il feed di azioni multimediali con Google TV, non devi creare entità separate per film o programmi TV, ma puoi creare un MediaActionFeedEntity che includa il campo obbligatorio DataFeedElementId. Questo ID deve essere univoco e corrispondere all'ID nel feed di azioni multimediali, in quanto consente di identificare i contenuti del feed importati ed eseguire ricerche di contenuti multimediali.

val id = "dataFeedElementId"

MovieEntity

Ecco un esempio di creazione di un MovieEntity con tutti i campi obbligatori:

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

Puoi fornire dati aggiuntivi come generi, classificazioni dei contenuti, data di uscita, motivo del consiglio e finestre temporali di disponibilità, che possono essere utilizzati da Google TV per scopi di visualizzazione o filtro avanzati.

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

Ecco un esempio di creazione di un TvShowEntity con tutti i campi obbligatori:

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

Facoltativamente, fornisci dati aggiuntivi come generi, classificazioni dei contenuti, motivo del consiglio, prezzo dell'offerta, numero di stagioni o finestra temporale di disponibilità, che potrebbero essere utilizzati da Google TV per scopi di visualizzazione o filtro avanzati.

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

Ecco un esempio di creazione di un MediaActionFeedEntity con tutti i campi obbligatori:

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

Facoltativamente, fornisci dati aggiuntivi come descrizione, motivo del consiglio e finestra temporale di visualizzazione, che potrebbero essere utilizzati da Google TV per visualizzazioni avanzate o per scopi di filtro.

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

Rappresenta un canale TV in diretta. Ecco un esempio di creazione di un LiveTvChannelEntity con tutti i campi obbligatori:

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

Se vuoi, fornisci dati aggiuntivi, come le classificazioni dei contenuti o il motivo del consiglio.

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

Rappresenta una scheda di un programma TV in diretta trasmesso o programmato per la trasmissione su un canale TV in diretta. Ecco un esempio di creazione di un LiveTvProgramEntity con tutti i campi obbligatori:

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

Se vuoi, puoi fornire dati aggiuntivi, come classificazioni dei contenuti, generi o il motivo del consiglio.

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