Engage SDK Watch: istruzioni per l'integrazione tecnica di terze parti

Google sta sviluppando una piattaforma sul dispositivo che organizza le app degli utenti per verticali e consente una nuova esperienza immersiva per la fruizione e la scoperta dei contenuti delle app personalizzate. Questa esperienza a schermo intero offre agli sviluppatori partner l'opportunità di mostrare i loro migliori contenuti avanzati in un canale dedicato al di fuori della loro app.

Questa guida contiene istruzioni che consentono agli sviluppatori partner di integrare i propri contenuti video utilizzando l'SDK Engage per compilare sia questa nuova area di superficie che le piattaforme Google esistenti.

Dettagli integrazione

Terminologia

Questa integrazione include i seguenti tre tipi di cluster: Recommendation, Continuazione e In primo piano.

  • I cluster di consigli mostrano suggerimenti personalizzati sui contenuti da guardare da un singolo sviluppatore partner.

    I consigli hanno la seguente struttura:

    • Cluster di suggerimenti:una visualizzazione UI contenente un gruppo di suggerimenti dallo stesso partner di sviluppatori.

      Figura 1. UI di Entertainment Space che mostra un cluster di suggerimenti di un singolo partner.
    • Entità: un oggetto che rappresenta un singolo elemento in un cluster. Un'entità può essere un film, un programma TV, una serie TV, un video in diretta e altro ancora. Consulta la sezione Fornire i dati delle entità per un elenco dei tipi di entità supportati.

      Figura 2. UI di Entertainment Space che mostra una singola entità all'interno del cluster di suggerimenti di un singolo partner.
  • Il cluster Continuazione mostra i video da finire e le nuove uscite pertinenti di diversi sviluppatori partner in un unico raggruppamento dell'interfaccia utente. Ogni partner sviluppatore potrà trasmettere un massimo di 10 entità nel cluster Continuazione. La ricerca ha dimostrato che i consigli personalizzati, insieme ai contenuti di continuazione personalizzati, creano il miglior coinvolgimento degli utenti.

    Figura 3. UI di Entertainment Space che mostra un cluster di continuazione con suggerimenti non completati da più partner (al momento è visibile un solo suggerimento).
  • Il cluster In primo piano mostra una selezione di entità di più partner di sviluppatori in un raggruppamento di UI. Ci sarà un singolo cluster in primo piano, visualizzato nella parte superiore dell'interfaccia utente con un posizionamento prioritario sopra tutti i cluster dei suggerimenti. Ogni partner di sviluppo potrà trasmettere fino a 10 entità nel cluster in primo piano.

    Figura 4. UI di Entertainment Space che mostra un cluster In primo piano con suggerimenti di più partner (al momento è visibile un solo suggerimento).

Attività preliminare

Livello API minimo: 19

Aggiungi la raccolta com.google.android.engage:engage-core alla tua app:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

Per maggiori informazioni, vedi Visibilità dei pacchetti in Android 11.

Riepilogo

La progettazione si basa sull'implementazione di un servizio associato.

I dati che un client può pubblicare sono soggetti ai seguenti limiti per diversi tipi di cluster:

Tipo di cluster Limiti del cluster Limiti massimi di entità in un cluster
Cluster di suggerimenti Al massimo 5 Al massimo 50
Cluster di continuazione Al massimo 1 Al massimo 10
Cluster in primo piano Al massimo 1 Al massimo 10

Passaggio 0: migrazione dall'integrazione esistente dell'SDK Media Home

Mappa i modelli dei dati da integrazioni esistenti

Se stai eseguendo la migrazione da un'integrazione esistente di Media Home, la seguente tabella illustra come mappare i modelli dei dati negli SDK esistenti al nuovo SDK Engage:

Equivalente dell'integrazione di MediaHomeVideoContract Equivalente dell'integrazione dell'SDK per il coinvolgimento
com.google.android.mediahome.video.PreviewChannel com.google.android.engage.common.datamodel.RecommendationCluster
com.google.android.mediahome.video.PreviewChannel.Builder com.google.android.engage.common.datamodel.RecommendationCluster.Builder
com.google.android.mediahome.video.PreviewChannelHelper com.google.android.engage.video.service.AppEngageVideoClient
com.google.android.mediahome.video.PreviewProgram Diviso in corsi separati: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.PreviewProgram.Builder Suddivisione in generatori in classi separate: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.VideoContract Non serve più.
com.google.android.mediahome.video.WatchNextProgram Suddivisione in attributi in classi separate: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity
com.google.android.mediahome.video.WatchNextProgram.Builder Suddivisione in attributi in classi separate: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity

Confronto tra la pubblicazione di cluster nell'SDK Media Home e nell'SDK Engage

Con l'SDK Media Home, i cluster e le entità sono stati pubblicati tramite API separate:

// 1. Fetch existing channels
List<PreviewChannel> channels = PreviewChannelHelper.getAllChannels();

// 2. If there are no channels, publish new channels
long channelId = PreviewChannelHelper.publishChannel(builder.build());

// 3. If there are existing channels, decide whether to update channel contents
PreviewChannelHelper.updatePreviewChannel(channelId, builder.build());

// 4. Delete all programs in the channel
PreviewChannelHelper.deleteAllPreviewProgramsByChannelId(channelId);

// 5. publish new programs in the channel
PreviewChannelHelper.publishPreviewProgram(builder.build());

Con l'SDK Engage, la pubblicazione di cluster ed entità viene combinata in un'unica chiamata API. Tutte le entità che appartengono a un cluster vengono pubblicate insieme al cluster:

Kotlin

RecommendationCluster.Builder()
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .setTitle("Top Picks For You")
            .build()

Java

new RecommendationCluster.Builder()
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .setTitle("Top Picks For You")
                        .build();

Passaggio 1: fornisci i dati dell'entità

L'SDK ha definito diverse entità per rappresentare ogni tipo di elemento. Supportiamo le seguenti entità per la categoria Watch:

  1. MovieEntity
  2. TvShowEntity
  3. TvSeasonEntity
  4. TvEpisodeEntity
  5. LiveStreamingVideoEntity
  6. VideoClipEntity

Il grafico riportato di seguito illustra gli attributi e i requisiti di ogni tipo.

MovieEntity

Attributo Requisito Notes
Nome Obbligatorie
Immagini poster Obbligatorie È richiesta almeno un'immagine e deve essere fornita con proporzioni. (È preferibile l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi).

Per indicazioni, consulta le Specifiche delle immagini.

URI di riproduzione Obbligatorie

Il link diretto all'app del fornitore per iniziare la riproduzione del film.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

URI pagina delle informazioni Facoltativo

Il link diretto all'app del fornitore per mostrare i dettagli del film.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

Data di uscita Obbligatorie In millisecondi di epoca.
Disponibilità Obbligatorie

AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni.

FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente ha acquistato un abbonamento.

PAID_CONTENT: i contenuti richiedono l'acquisto o il noleggio da parte dell'utente.

PURCHASED: i contenuti sono stati acquistati o noleggiati dall'utente.

Prezzo offerta Facoltativo Testo libero
Durata Obbligatorie In millisecondi.
Genere Obbligatorie Testo libero
Classificazioni dei contenuti Obbligatorie Testo libero, segui lo standard di settore. (Esempio)
Tipo di video successivo Obbligatorio in modo condizionale

Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei quattro tipi seguenti:

CONTINUA: l'utente ha già guardato più di 1 minuto di questi contenuti.

NOVITÀ: l'utente ha guardato tutte le puntate disponibili di alcuni contenuti episodici, ma è diventato disponibile una nuova puntata ed è esattamente un episodio non guardato. Funziona per i programmi TV, le partite di calcio registrate in una serie e così via.

SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma è rimasto più di un episodio o esattamente un episodio rimanente in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente abbia iniziato a guardare i contenuti a puntate.

LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente il contenuto successivo che vuole guardare.

Durata ultimo coinvolgimento Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuazione. In epoca millisecondi.
Data/ora posizione ultima riproduzione Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuation e WatchNextType è continue. In millisecondi di epoca.

TvShowEntity

Attributo Requisito Notes
Nome Obbligatorie
Immagini poster Obbligatorie È richiesta almeno un'immagine e deve essere fornita con proporzioni. (È preferibile l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi).

Per indicazioni, consulta le Specifiche delle immagini.

URI pagina delle informazioni Obbligatorie

Il link diretto all'app del fornitore per mostrare i dettagli del programma TV.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

URI di riproduzione Facoltativo

Il link diretto all'app del fornitore per iniziare a riprodurre il programma TV.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

Data di messa in onda del primo episodio Obbligatorie In millisecondi di epoca.
Data di messa in onda dell'ultima puntata Facoltativo In millisecondi di epoca.
Disponibilità Obbligatorie

AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni.

FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente ha acquistato un abbonamento.

PAID_CONTENT: i contenuti richiedono l'acquisto o il noleggio da parte dell'utente.

PURCHASED: i contenuti sono stati acquistati o noleggiati dall'utente.

Prezzo offerta Facoltativo Testo libero
Numero di stagioni Obbligatorie Intero positivo
Genere Obbligatorie Testo libero
Classificazioni dei contenuti Obbligatorie Testo libero, segui lo standard di settore. (Esempio)
Tipo di video successivo Obbligatorio in modo condizionale

Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei quattro tipi seguenti:

CONTINUA: l'utente ha già guardato più di 1 minuto di questi contenuti.

NOVITÀ: l'utente ha guardato tutte le puntate disponibili di alcuni contenuti episodici, ma è diventato disponibile una nuova puntata ed è esattamente un episodio non guardato. Funziona per i programmi TV, le partite di calcio registrate in una serie e così via.

SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma è rimasto più di un episodio o esattamente un episodio rimanente in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente abbia iniziato a guardare i contenuti a puntate.

LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente il contenuto successivo che vuole guardare.

Durata ultimo coinvolgimento Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuazione. In epoca millisecondi.
Data/ora posizione ultima riproduzione Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuation e WatchNextType è continue. In millisecondi di epoca.

TvSeasonEntity

Attributo Requisito Notes
Nome Obbligatorie
Immagini poster Obbligatorie È richiesta almeno un'immagine e deve essere fornita con proporzioni. (È preferibile l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi).

Per indicazioni, consulta le Specifiche delle immagini.

URI pagina delle informazioni Obbligatorie

Il link diretto all'app del fornitore per mostrare i dettagli della stagione del programma TV.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

URI di riproduzione Facoltativo

Il link diretto all'app del fornitore per iniziare a riprodurre la stagione del programma TV.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

Numero stagione visualizzato

Facoltativo

Disponibile nella versione 1.3.1

Stringa
Data di messa in onda del primo episodio Obbligatorie In millisecondi di epoca.
Data di messa in onda dell'ultima puntata Facoltativo In millisecondi di epoca.
Disponibilità Obbligatorie

AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni.

FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente ha acquistato un abbonamento.

PAID_CONTENT: i contenuti richiedono l'acquisto o il noleggio da parte dell'utente.

PURCHASED: i contenuti sono stati acquistati o noleggiati dall'utente.

Prezzo offerta Facoltativo Testo libero
Numero di puntate Obbligatorie Intero positivo
Genere Obbligatorie Testo libero
Classificazioni dei contenuti Obbligatorie Testo libero, segui lo standard di settore. (Esempio)
Tipo di video successivo Obbligatorio in modo condizionale

Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei quattro tipi seguenti:

CONTINUA: l'utente ha già guardato più di 1 minuto di questi contenuti.

NOVITÀ: l'utente ha guardato tutte le puntate disponibili di alcuni contenuti episodici, ma è diventato disponibile una nuova puntata ed è esattamente un episodio non guardato. Funziona per i programmi TV, le partite di calcio registrate in una serie e così via.

SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma è rimasto più di un episodio o esattamente un episodio rimanente in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente abbia iniziato a guardare i contenuti a puntate.

LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente il contenuto successivo che vuole guardare.

Durata ultimo coinvolgimento Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuazione. In epoca millisecondi.
Data/ora posizione ultima riproduzione Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuation e WatchNextType è continue. In millisecondi di epoca.

TvEpisodeEntity

Attributo Requisito Notes
Nome Obbligatorie
Immagini poster Obbligatorie È richiesta almeno un'immagine e deve essere fornita con proporzioni. (È preferibile l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi).

Per indicazioni, consulta le Specifiche delle immagini.

URI di riproduzione Obbligatorie

Il link diretto all'app del fornitore per iniziare a riprodurre la puntata.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

URI pagina delle informazioni Facoltativo

Il link diretto all'app del fornitore per mostrare i dettagli dell'episodio del programma TV.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

Visualizza il numero della puntata

Facoltativo

Disponibile nella versione 1.3.1

Stringa
Data messa in onda Obbligatorie In millisecondi di epoca.
Disponibilità Obbligatorie

AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni.

FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente ha acquistato un abbonamento.

PAID_CONTENT: i contenuti richiedono l'acquisto o il noleggio da parte dell'utente.

PURCHASED: i contenuti sono stati acquistati o noleggiati dall'utente.

Prezzo offerta Facoltativo Testo libero
Durata Obbligatorie Deve essere un valore positivo in millisecondi.
Genere Obbligatorie Testo libero
Classificazioni dei contenuti Obbligatorie Testo libero, segui lo standard di settore. (Esempio)
Tipo di video successivo Obbligatorio in modo condizionale

Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei quattro tipi seguenti:

CONTINUA: l'utente ha già guardato più di 1 minuto di questi contenuti.

NOVITÀ: l'utente ha guardato tutte le puntate disponibili di alcuni contenuti episodici, ma è diventato disponibile una nuova puntata ed è esattamente un episodio non guardato. Funziona per i programmi TV, le partite di calcio registrate in una serie e così via.

SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma è rimasto più di un episodio o esattamente un episodio rimanente in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente abbia iniziato a guardare i contenuti a puntate.

LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente il contenuto successivo che vuole guardare.

Durata ultimo coinvolgimento Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuazione. In epoca millisecondi.
Data/ora posizione ultima riproduzione Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuation e WatchNextType è continue. In millisecondi di epoca.

LiveStreamingVideoEntity

Attributo Requisito Notes
Nome Obbligatorie
Immagini poster Obbligatorie È richiesta almeno un'immagine e deve essere fornita con proporzioni. (È preferibile l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi).

Per indicazioni, consulta le Specifiche delle immagini.

URI di riproduzione Obbligatorie

Il link diretto all'app del fornitore per avviare la riproduzione del video.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

Emittente Obbligatorie Testo libero
Ora di inizio Facoltativo In millisecondi di epoca.
Ora di fine Facoltativo In millisecondi di epoca.
Numero di visualizzazioni Facoltativo Testo libero, deve essere localizzato.
Tipo di video successivo Obbligatorio in modo condizionale

Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei quattro tipi seguenti:

CONTINUA: l'utente ha già guardato più di 1 minuto di questi contenuti.

NOVITÀ: l'utente ha guardato tutte le puntate disponibili di alcuni contenuti episodici, ma è diventato disponibile una nuova puntata ed è esattamente un episodio non guardato. Funziona per i programmi TV, le partite di calcio registrate in una serie e così via.

SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma è rimasto più di un episodio o esattamente un episodio rimanente in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente abbia iniziato a guardare i contenuti a puntate.

LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente il contenuto successivo che vuole guardare.

Durata ultimo coinvolgimento Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuazione. In epoca millisecondi.
Data/ora posizione ultima riproduzione Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuation e WatchNextType è continue. In millisecondi di epoca.

VideoClipEntity

L'oggetto VideoClipEntity rappresenta un'entità video proveniente da social media, come TikTok o YouTube.

Attributo Requisito Notes
Nome Obbligatorie
Immagini poster Obbligatorie È richiesta almeno un'immagine e deve essere fornita con proporzioni. (È preferibile l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi).

Per indicazioni, consulta le Specifiche delle immagini.

URI di riproduzione Obbligatorie

Il link diretto all'app del fornitore per avviare la riproduzione del video.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

Data e ora di creazione Obbligatorie In millisecondi di epoca.
Durata Obbligatorie Deve essere un valore positivo in millisecondi.
Creatore Obbligatorie Testo libero
Immagine autore Facoltativo Immagine dell'avatar del creator
Numero di visualizzazioni Facoltativo Testo libero, deve essere localizzato.
Tipo di video successivo Obbligatorio in modo condizionale

Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei quattro tipi seguenti:

CONTINUA: l'utente ha già guardato più di 1 minuto di questi contenuti.

NOVITÀ: l'utente ha guardato tutte le puntate disponibili di alcuni contenuti episodici, ma è diventato disponibile una nuova puntata ed è esattamente un episodio non guardato. Funziona per i programmi TV, le partite di calcio registrate in una serie e così via.

SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma è rimasto più di un episodio o esattamente un episodio rimanente in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente abbia iniziato a guardare i contenuti a puntate.

LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente il contenuto successivo che vuole guardare.

Durata ultimo coinvolgimento Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuazione. In epoca millisecondi.
Data/ora posizione ultima riproduzione Obbligatorio in modo condizionale Deve essere fornito quando l'elemento si trova nel cluster Continuation e WatchNextType è continue. In millisecondi di epoca.

Specifiche per le immagini

La seguente sezione elenca le specifiche obbligatorie per gli asset immagine:

Formati file

PNG, JPG, GIF statica, WebP

Dimensioni massime del file

5120 kB

Consigli aggiuntivi

  • Area di sicurezza dell'immagine: inserisci i contenuti importanti al centro dell'immagine in modo da occuparne l'80%.

Esempio

Kotlin

var movie = MovieEntity.Builder()
    .setName("Avengers")
    .addPosterImage(Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
    .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
    .setReleaseDateEpochMillis(1633032895L)
    .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
    .setDurationMillis(12345678L)
    .addGenre("action")
    .addContentRating("R")
    .setWatchNextType(WatchNextType.TYPE_NEW)
    .setLastEngagementTimeMillis(1664568895L)
    .build()

Java

MovieEntity movie = new MovieEntity.Builder()
                  .setName("Avengers")
                  .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
                  .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
                  .setReleaseDateEpochMillis(1633032895L)
                  .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
                  .setDurationMillis(12345678L)
                  .addGenre("action")
                  .addContentRating("R")
                  .setWatchNextType(WatchNextType.TYPE_NEW)
                  .setLastEngagementTimeMillis(1664568895L)
                  .build();

Passaggio 2: fornisci i dati del cluster

È consigliabile che il job di pubblicazione dei contenuti venga eseguito in background (ad esempio utilizzando WorkManager) e pianificato regolarmente o in base agli eventi (ad esempio, ogni volta che l'utente apre l'app o quando l'utente ha appena aggiunto qualcosa al carrello).

AppEngagePublishClient è responsabile della pubblicazione dei cluster. Nel client sono disponibili le seguenti API:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishContinuationCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteContinuationCluster
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

Questa API viene utilizzata per verificare se il servizio è disponibile per l'integrazione e se i contenuti possono essere presentati sul dispositivo.

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

publishRecommendationClusters

Questa API viene utilizzata per pubblicare un elenco di oggetti RecommendationCluster.

Kotlin

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

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

  • I dati esistenti relativi a RecommendationCluster dello sviluppatore partner verranno rimossi.
  • I dati della richiesta vengono analizzati e archiviati nel cluster di suggerimenti aggiornato.

In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

publishFeaturedCluster

Questa API viene utilizzata per pubblicare un elenco di oggetti FeaturedCluster.

Kotlin

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

  • I dati esistenti relativi a FeaturedCluster dello sviluppatore partner verranno rimossi.
  • I dati della richiesta vengono analizzati e archiviati nel cluster in primo piano aggiornato.

In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

publishContinuationCluster

Questa API viene utilizzata per pubblicare un oggetto ContinuationCluster.

Kotlin

client.publishContinuationCluster(
    PublishContinuationClusterRequest.Builder()
      .setContinuationCluster(
        ContinuationCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishContinuationCluster(
            new PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    new ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

  • I dati esistenti relativi a ContinuationCluster dello sviluppatore partner verranno rimossi.
  • I dati della richiesta vengono analizzati e archiviati nel cluster di continuazione aggiornato.

In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

publishUserAccountManagementRequest

Questa API viene utilizzata per pubblicare una scheda di accesso . L'azione di accesso indirizza gli utenti alla pagina di accesso dell'app, in modo che quest'ultima possa pubblicare contenuti (o fornire contenuti più personalizzati)

I seguenti metadati fanno parte della scheda di accesso:

Attributo Requisito Descrizione
URI azione Obbligatorio Link diretto all'azione (ad esempio, per passare alla pagina di accesso all'app)
Immagine Facoltativo: se non viene specificato, è necessario indicare il titolo

Immagine mostrata sulla scheda

Immagini con proporzioni 16:9 con una risoluzione di 1264 x 712

Titolo Facoltativo: se non viene fornita, è necessario fornire l'immagine Titolo sulla scheda
Testo dell'azione Facoltativo Testo mostrato sull'invito all'azione (ad es. Accedi)
Sottotitolo Facoltativo Sottotitolo facoltativo sulla scheda

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

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

  • I dati UserAccountManagementCluster esistenti dello sviluppatore partner vengono rimossi.
  • I dati della richiesta vengono analizzati e archiviati nel cluster UserAccountManagementCluster aggiornato.

In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

updatePublishStatus

Se, per qualsiasi motivo aziendale interno, nessuno dei cluster viene pubblicato, ti consigliamo vivamente di aggiornare lo stato di pubblicazione utilizzando l'API updatePubblicaStatus. Questo è importante perché :

  • Fornire lo stato in tutti gli scenari, anche quando i contenuti vengono pubblicati (STATO == PUBBLICATO), è fondamentale per compilare le dashboard che usano questo stato esplicito per comunicare lo stato di integrità e altre metriche dell'integrazione.
  • Se non vengono pubblicati contenuti, ma lo stato dell'integrazione non è interrotto (STATUS == NOT_PUBLISHERED), Google può evitare di attivare avvisi nelle dashboard sullo stato dell'app. Conferma che i contenuti non sono stati pubblicati a causa di una situazione prevista dal punto di vista del fornitore.
  • Consente agli sviluppatori di capire quando i dati vengono pubblicati o meno.
  • Google potrebbe utilizzare i codici di stato per sollecitare l'utente a eseguire determinate azioni nell'app in modo che possa vedere i contenuti dell'app o superarli.

Ecco un elenco di codici di stato idonei per la pubblicazione :

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

Se i contenuti non vengono pubblicati perché un utente non ha eseguito l'accesso, Google consiglia di pubblicare la scheda di accesso. Se per qualsiasi motivo i fornitori non sono in grado di pubblicare la scheda di accesso, ti consigliamo di chiamare l'API updatepublishStatus con il codice di stato NOT_PUBLISHERED_REQUIRES_SIGN_IN

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationClusters

Questa API viene utilizzata per eliminare i contenuti dei cluster dei suggerimenti.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

Quando il servizio riceve la richiesta, rimuove i dati esistenti dai cluster dei suggerimenti. In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

deleteFeaturedCluster

Questa API viene utilizzata per eliminare i contenuti del cluster in primo piano.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Quando il servizio riceve la richiesta, rimuove i dati esistenti dal cluster in primo piano. In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

deleteContinuationCluster

Questa API viene utilizzata per eliminare i contenuti del cluster di continuazione.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

Quando il servizio riceve la richiesta, rimuove i dati esistenti dal cluster di continuazione. In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

deleteUserManagementCluster

Questa API viene utilizzata per eliminare i contenuti del cluster UserAccountManagement.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Quando il servizio riceve la richiesta, rimuove i dati esistenti dal cluster UserAccountManagement. In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

deleteClusters

Questa API viene utilizzata per eliminare i contenuti di un determinato tipo di cluster.

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_CONTINUATION)
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_CONTINUATION)
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                .build());

Quando il servizio riceve la richiesta, rimuove i dati esistenti da tutti i cluster corrispondenti ai tipi di cluster specificati. I client possono scegliere di passare uno o più tipi di cluster. In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

Gestione degli errori

Ti consigliamo vivamente di ascoltare il risultato dell'attività dalle API di pubblicazione, in modo che sia possibile eseguire un'azione di follow-up per recuperare e inviare nuovamente un'attività riuscita.

Kotlin

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

L'errore viene restituito come AppEngageException e la causa è inclusa sotto forma di codice di errore.

Codice di errore Nota
SERVICE_NOT_FOUND Il servizio non è disponibile sul dispositivo specificato.
SERVICE_NOT_AVAILABLE Il servizio è disponibile sul dispositivo specificato, ma non è disponibile al momento della chiamata (ad esempio, è esplicitamente disabilitato).
SERVICE_CALL_EXECUTION_FAILURE Esecuzione dell'attività non riuscita a causa di problemi di thread. In questo caso, è possibile riprovare.
SERVICE_CALL_PERMISSION_DENIED Il chiamante non è autorizzato a effettuare la chiamata di servizio.
SERVICE_CALL_INVALID_ARGUMENT La richiesta contiene dati non validi (ad esempio, più del numero consentito di cluster).
SERVICE_CALL_INTERNAL Si è verificato un errore sul lato del servizio.
SERVICE_CALL_RESOURCE_EXHAUSTED La chiamata all'assistenza viene effettuata troppo spesso.

Passaggio 3: gestisci gli intent di trasmissione

Oltre a effettuare chiamate all'API Publishing Content tramite un job, è necessario anche configurare una BroadcastReceiver per ricevere la richiesta di pubblicazione di contenuti.

L'obiettivo degli intent di trasmissione è principalmente la riattivazione dell'app e la forzatura della sincronizzazione dei dati. Gli intent di trasmissione non sono progettati per essere inviati molto spesso. Viene attivato solo quando il servizio Google Engage stabilisce che i contenuti potrebbero essere inattivi (ad esempio, dopo una settimana). In questo modo, è più sicura che l'utente possa usufruire di una nuova esperienza con i contenuti, anche se l'applicazione non è stata eseguita per un lungo periodo di tempo.

BroadcastReceiver deve essere configurato nei due modi seguenti:

  • Registra dinamicamente un'istanza della classe BroadcastReceiver utilizzando Context.registerReceiver(). Ciò consente la comunicazione da applicazioni ancora attive in memoria.

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION))
}

Java

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}
  • Dichiarare in modo statico un'implementazione con il tag <receiver> nel file AndroidManifest.xml. Ciò consente all'applicazione di ricevere intent di trasmissione quando non è in esecuzione e di pubblicare i contenuti.
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

Il servizio invia i seguenti intent:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION Ti consigliamo di avviare una chiamata publishRecommendationClusters quando ricevi questo intent.
  • com.google.android.engage.action.PUBLISH_FEATURED Ti consigliamo di avviare una chiamata publishFeaturedCluster quando ricevi questo intent.
  • com.google.android.engage.action.PUBLISH_CONTINUATION Ti consigliamo di avviare una chiamata publishContinuationCluster quando ricevi questo intent.

Flusso di lavoro di integrazione

Per una guida passo passo sulla verifica dell'integrazione dopo il completamento, consulta Flusso di lavoro dell'integrazione degli sviluppatori per Coinvolgimento.

Domande frequenti

Consulta le Domande frequenti sull'SDK Engage per le domande frequenti.

Contact

Contatta engagement-developers@google.com in caso di domande durante il processo di integrazione.

Passaggi successivi

Dopo aver completato l'integrazione, i passaggi successivi sono i seguenti:

  • Invia un'email all'indirizzo engagement-developers@google.com e allega il tuo APK integrato pronto per i test da parte di Google.
  • Google esegue una verifica e una revisione interna per garantire che l'integrazione funzioni come previsto. Se sono necessarie modifiche, Google ti contatta fornendoti i dettagli necessari.
  • Quando il test è stato completato e non sono necessarie modifiche, Google ti contatta per informarti che puoi iniziare a pubblicare l'APK aggiornato e integrato nel Play Store.
  • Dopo che Google avrà confermato che l'APK aggiornato è stato pubblicato sul Play Store, i tuoi cluster Consiglio, In primo piano e Continuazione potrebbero essere pubblicati e visibili agli utenti.