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

Importante: l'SDK Engage ha sostituito Media Home, che ora è deprecato. Se hai un'integrazione Media Home esistente, segui le istruzioni riportate in queste guide per eseguire la migrazione dei tuoi contenuti all'SDK Engage, che consente di pubblicarli su più dispositivi e fattori di forma. In caso di domande, contatta [e-mail].

Aumenta il coinvolgimento con l'app raggiungendo i tuoi utenti ovunque si trovino. Integra l'SDK Engage per fornire contenuti Continua a guardare e suggerimenti personalizzati direttamente agli utenti su più piattaforme on-device: Raccolte, Entertainment Space e Play Store. L'integrazione aggiunge meno di 50 KB (compressi) all'APK medio e richiede circa una settimana di lavoro per la maggior parte delle app. Scopri di più sul nostro sito aziendale.

Questa guida contiene istruzioni per gli sviluppatori partner per l'integrazione dei loro contenuti video, utilizzando l'SDK Engage per compilare sia questa nuova area di superficie sia le piattaforme Google esistenti.

Nota: consulta la guida all'integrazione della TV per scoprire di più sull'esperienza Continua a guardare su Google TV.

Supporto delle categorie e piattaforme

L'idoneità alla piattaforma dell'SDK Engage si basa sulla categoria di contenuti della tua app. Utilizza la tabella seguente per determinare la tua idoneità per piattaforme specifiche:

Stato	Categoria di contenuti o caso d'uso	Piattaforme supportate
Supportato (Idoneo su tutte le piattaforme)	Streaming di film e programmi TV TV in diretta/Sport Video clip on demand Video sportivi Serie di corti drammatici Podcast video	Raccolte Entertainment Space Scheda App Play Store Scheda Tu del Play Store Pagina della scheda del Play Store
Parzialmente supportata (Idonea su alcune piattaforme)	Video clip da app di notizie	Raccolte Entertainment Space
Non supportato	Telecomandi Strumenti per il download, player ed editor di video Recensioni di film e programmi TV Biglietti del cinema Guide TV Videochiamate e stanze virtuali

Competenze Android

Visualizza su GitHub

Integra l'SDK Engage

Utilizza la competenza Android dell'SDK Engage per integrare, eseguire il debug e risolvere i problemi di implementazione.

Per installare lo skill dalla CLI Android, esegui:

android skills add engage-sdk-integration

Dettaglio dell'integrazione

Questa sezione descrive i passaggi, i modelli di dati e la terminologia necessari per l'integrazione con l'SDK Engage per i contenuti video.

Terminologia

Questa integrazione include i seguenti tre tipi di cluster: Contenuti consigliati, Continua e In primo piano.

• I cluster di contenuti consigliati mostrano suggerimenti personalizzati per i contenuti da guardare di un singolo sviluppatore partner.

  I suggerimenti hanno la seguente struttura:

  • Cluster di contenuti consigliati:una visualizzazione dell'interfaccia utente che contiene un gruppo di contenuti consigliati dello stesso partner sviluppatore.

    

    Figura 1. UI di Entertainment Space che mostra un cluster di consigli 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 Fornisci i dati delle entità per un elenco dei tipi di entità supportati.

    

    Figura 2. Interfaccia utente di Entertainment Space che mostra una singola entità all'interno di un cluster di contenuti consigliati di un singolo partner.

• Il cluster Continua mostra i video non completati e le nuove puntate pertinenti rilasciate da più sviluppatori partner in un unico raggruppamento dell'interfaccia utente. Ogni partner sviluppatore potrà trasmettere un massimo di 10 entità nel cluster di continuazione. Le ricerche hanno 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 contenuti consigliati non completati di più partner (al momento è visibile un solo contenuto consigliato).

• Il cluster In primo piano mostra una selezione di entità di più partner sviluppatori in un unico raggruppamento dell'interfaccia utente. Ci sarà un unico cluster In evidenza, che viene visualizzato nella parte superiore della UI con un posizionamento prioritario sopra tutti i cluster di Contenuti consigliati. Ogni partner sviluppatore potrà trasmettere fino a 10 entità nel cluster In evidenza.

  

  Figura 4. Interfaccia utente di Entertainment Space che mostra un cluster In primo piano con consigli di più partner (al momento è visibile un solo consiglio).

Preparazione

Livello API minimo: 19

Aggiungi la libreria 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.6.0'
}

Per maggiori informazioni, consulta la pagina Visibilità dei pacchetti in Android 11.

Riepilogo

Il design si basa sull'implementazione di un servizio associato.

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

Tipo di cluster	Limiti dei cluster	Limiti massimi di entità in un cluster
Cluster di suggerimenti	Al massimo 7	Al massimo 50
Cluster di continuazione	Al massimo 1	Al massimo 20
Cluster in primo piano	Al massimo 1	Al massimo 20

Importante: l'SDK Engage ha sostituito Media Home, che ora è deprecato. Se hai un'integrazione Media Home esistente, segui le istruzioni riportate nel passaggio 0 per eseguire la migrazione dei tuoi contenuti all'SDK Engage, che consente di pubblicare i tuoi contenuti su più dispositivi e fattori di forma. Contatta [e-mail]. Se non hai un'integrazione Media Home esistente, vai al passaggio 1.

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

Questa sezione descrive come eseguire la migrazione dei modelli di dati e delle chiamate API dell'SDK Media Home esistenti all'SDK Engage.

Mappa i modelli di dati dall'integrazione esistente

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

Equivalente dell'integrazione MediaHomeVideoContract	Equivalente dell'integrazione dell'SDK Engage
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	Suddiviso in classi separate: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.PreviewProgram.Builder	Suddivisi in builder in classi separate: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.VideoContract	Non più necessario.
com.google.android.mediahome.video.WatchNextProgram	Suddiviso in attributi in classi separate: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity
com.google.android.mediahome.video.WatchNextProgram.Builder	Suddivisi in attributi in classi separate: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity

Pubblicazione di cluster nell'SDK Media Home rispetto all'SDK Engage

Con l'SDK Media Home, i cluster e le entità venivano 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à è combinata in un'unica chiamata API. Tutte le entità che appartengono a un cluster vengono pubblicate insieme a quel 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 della persona giuridica

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

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

Il grafico seguente illustra gli attributi e i requisiti per ogni tipo.

MovieEntity

Attributo	Requisito	Note
Nome	Obbligatorio
Immagini del poster	Obbligatorio	È richiesta almeno un'immagine, che deve essere fornita con le proporzioni. (È preferibile il formato orizzontale, ma è consigliabile passare immagini sia verticali che orizzontali per scenari diversi.) Per indicazioni, consulta le specifiche per le immagini.
URI di riproduzione	Obbligatorio per i dispositivi mobili	Il deep link all'app del fornitore per avviare la riproduzione del film. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
URI di riproduzione specifici della piattaforma	Facoltativo per i dispositivi mobili; obbligatorio per Google TV	Deep link specifici per la piattaforma all'app del fornitore per avviare la riproduzione del film.
URI della pagina di informazioni	Facoltativo	Il deep link all'app del fornitore per mostrare i dettagli del film. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
Data di uscita	Facoltativo	In millisecondi dall'epoca.
Disponibilità	Facoltativo	AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni. FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente acquista 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	Obbligatorio	In millisecondi.
Genere	Facoltativo	Testo libero
Classificazioni dei contenuti	Facoltativo	Testo libero, segui lo standard di settore. (Esempio)
Call to action text	Facoltativo	Testo libero da visualizzare come invito all'azione.
Tag	Facoltativo	Elenco di tag associati all'entità.
Tipo di Cosa guardare	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e deve essere uno dei seguenti quattro tipi: CONTINUE: l'utente ha già guardato più di 1 minuto di questo contenuto. NEW: l'utente ha guardato tutti gli episodi disponibili di alcuni contenuti a puntate, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i contenuti a puntate, come i programmi TV o le partite di calcio registrate di una serie. NEXT: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimangono ancora più di un episodio o esattamente un episodio in cui l'ultimo episodio non è "NEW" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti a episodi. WATCHLIST: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in un secondo momento.
Ora ultimo coinvolgimento	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi dall'epoca.
Data/ora ultima posizione di riproduzione	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca.

TvShowEntity

Attributo	Requisito	Note
Nome	Obbligatorio
Immagini del poster	Obbligatorio	È richiesta almeno un'immagine, che deve essere fornita con le proporzioni. (È preferibile il formato orizzontale, ma è consigliabile passare immagini sia verticali che orizzontali per scenari diversi.) Per indicazioni, consulta le specifiche per le immagini.
URI della pagina di informazioni	Obbligatorio	Il deep link all'app del fornitore per mostrare i dettagli del programma TV. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
URI di riproduzione	Facoltativo	Il deep link all'app del fornitore per avviare la riproduzione del programma TV. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
URI di riproduzione specifici della piattaforma	Facoltativo per i dispositivi mobili; obbligatorio per Google TV	Deep link specifici per la piattaforma all'app del fornitore per avviare la riproduzione del programma TV.
Data di messa in onda della prima puntata	Facoltativo	In millisecondi dall'epoca.
Data di messa in onda dell'ultima puntata	Facoltativo	In millisecondi dall'epoca.
Disponibilità	Facoltativo	AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni. FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente acquista 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	Facoltativo	Intero positivo
Genere	Facoltativo	Testo libero
Classificazioni dei contenuti	Facoltativo	Testo libero, segui lo standard di settore. (Esempio)
Call to action text	Facoltativo	Testo libero da visualizzare come invito all'azione.
Tag	Facoltativo	Elenco di tag associati all'entità.
Tipo di Cosa guardare	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e deve essere uno dei seguenti quattro tipi: CONTINUE: l'utente ha già guardato più di 1 minuto di questo contenuto. NEW: l'utente ha guardato tutti gli episodi disponibili di alcuni contenuti a puntate, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i contenuti a puntate, come i programmi TV o le partite di calcio registrate di una serie. NEXT: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimangono ancora più di un episodio o esattamente un episodio in cui l'ultimo episodio non è "NEW" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti a episodi. WATCHLIST: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in un secondo momento.
Ora ultimo coinvolgimento	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi dall'epoca.
Data/ora ultima posizione di riproduzione	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca.

TvSeasonEntity

Attributo	Requisito	Note
Nome	Obbligatorio
Immagini del poster	Obbligatorio	È richiesta almeno un'immagine, che deve essere fornita con le proporzioni. (Il formato orizzontale è preferibile, ma è consigliabile passare immagini sia verticali che orizzontali per scenari diversi). Per indicazioni, consulta le specifiche per le immagini.
URI della pagina di informazioni	Obbligatorio	Il deep link all'app del fornitore per mostrare i dettagli della stagione del programma TV. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
URI di riproduzione	Facoltativo	Il deep link all'app del fornitore per avviare la riproduzione della stagione del programma TV. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
Mostra il numero della stagione	Facoltativo Disponibile nella versione 1.3.1	Stringa
Data di messa in onda della prima puntata	Facoltativo	In millisecondi dall'epoca.
Data di messa in onda dell'ultima puntata	Facoltativo	In millisecondi dall'epoca.
Disponibilità	Facoltativo	AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni. FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente acquista 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	Facoltativo	Intero positivo
Genere	Facoltativo	Testo libero
Classificazioni dei contenuti	Facoltativo	Testo libero, segui lo standard di settore. (Esempio)
Call to action text	Facoltativo	Testo libero da visualizzare come invito all'azione.
Tag	Facoltativo	Elenco di tag associati all'entità.
Tipo di Cosa guardare	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e deve essere uno dei seguenti quattro tipi: CONTINUE: l'utente ha già guardato più di 1 minuto di questo contenuto. NEW: l'utente ha guardato tutti gli episodi disponibili di alcuni contenuti a puntate, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i contenuti a puntate, come i programmi TV o le partite di calcio registrate di una serie. NEXT: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimangono ancora più di un episodio o esattamente un episodio in cui l'ultimo episodio non è "NEW" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti a episodi. WATCHLIST: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in un secondo momento.
Ora ultimo coinvolgimento	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi dall'epoca.
Data/ora ultima posizione di riproduzione	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca.

TvEpisodeEntity

Attributo	Requisito	Note
Nome	Obbligatorio
Immagini del poster	Obbligatorio	È richiesta almeno un'immagine, che deve essere fornita con le proporzioni. (È preferibile il formato orizzontale, ma è consigliabile passare immagini sia verticali che orizzontali per scenari diversi.) Per indicazioni, consulta le specifiche per le immagini.
URI di riproduzione	Obbligatorio per i dispositivi mobili	Il deep link all'app del fornitore per avviare la riproduzione della puntata. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
URI di riproduzione specifici della piattaforma	Facoltativo per i dispositivi mobili; obbligatorio per Google TV	Deep link specifici per la piattaforma all'app del fornitore per avviare la riproduzione della puntata.
URI della pagina di informazioni	Facoltativo	Il deep link all'app del fornitore per mostrare i dettagli della puntata del programma TV. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
Mostra titolo	Facoltativo per i dispositivi mobili; obbligatorio per Continua a guardare su Google TV	Il titolo del programma TV principale della puntata.
Numero stagione	Facoltativo per i dispositivi mobili; obbligatorio per Continua a guardare su Google TV	Stringa
Mostra il numero della puntata	Facoltativo per i dispositivi mobili; obbligatorio per Continua a guardare su Google TV Disponibile nella versione 1.3.1	Stringa
Data messa in onda	Facoltativo	In millisecondi dall'epoca.
Disponibilità	Facoltativo	AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni. FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente acquista 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	Obbligatorio	Deve essere un valore positivo in millisecondi.
Genere	Facoltativo	Testo libero
Classificazioni dei contenuti	Facoltativo	Testo libero, segui lo standard di settore. (Esempio)
Call to action text	Facoltativo	Testo libero da visualizzare come invito all'azione.
Tag	Facoltativo	Elenco di tag associati all'entità.
Tipo di Cosa guardare	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e deve essere uno dei seguenti quattro tipi: CONTINUE: l'utente ha già guardato più di 1 minuto di questo contenuto. NEW: l'utente ha guardato tutti gli episodi disponibili di alcuni contenuti a puntate, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i contenuti a puntate, come i programmi TV o le partite di calcio registrate di una serie. NEXT: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimangono ancora più di un episodio o esattamente un episodio in cui l'ultimo episodio non è "NEW" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti a episodi. WATCHLIST: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in un secondo momento.
Ora ultimo coinvolgimento	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi dall'epoca.
Data/ora ultima posizione di riproduzione	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca.

LiveStreamingVideoEntity

Attributo	Requisito	Note
Nome	Obbligatorio
Immagini del poster	Obbligatorio	È richiesta almeno un'immagine, che deve essere fornita con le proporzioni. (È preferibile il formato orizzontale, ma è consigliabile passare immagini sia verticali che orizzontali per scenari diversi.) Per indicazioni, consulta le specifiche per le immagini.
URI di riproduzione	Obbligatorio per i dispositivi mobili	Il deep link all'app del fornitore per avviare la riproduzione del video. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
URI di riproduzione specifici della piattaforma	Facoltativo per i dispositivi mobili; obbligatorio per Google TV	Deep link specifici per la piattaforma all'app del fornitore per avviare la riproduzione del video.
Emittente	Facoltativo	Testo libero
Ora di inizio	Facoltativo	In millisecondi dall'epoca.
Ora di fine	Facoltativo	In millisecondi dall'epoca.
Numero di visualizzazioni	Facoltativo	Testo libero, deve essere localizzato.
Call to action text	Facoltativo	Testo libero da visualizzare come invito all'azione.
Tag	Facoltativo	Elenco di tag associati all'entità.
Tipo di Cosa guardare	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e deve essere uno dei seguenti quattro tipi: CONTINUE: l'utente ha già guardato più di 1 minuto di questo contenuto. NEW: l'utente ha guardato tutti gli episodi disponibili di alcuni contenuti a puntate, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i contenuti a puntate, come i programmi TV o le partite di calcio registrate di una serie. NEXT: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimangono ancora più di un episodio o esattamente un episodio in cui l'ultimo episodio non è "NEW" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti a episodi. WATCHLIST: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in un secondo momento.
Ora ultimo coinvolgimento	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi dall'epoca.
Data/ora ultima posizione di riproduzione	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca.

VideoClipEntity

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

Attributo	Requisito	Note
Nome	Obbligatorio
Immagini del poster	Obbligatorio	È richiesta almeno un'immagine, che deve essere fornita con le proporzioni. (È preferibile il formato orizzontale, ma è consigliabile passare immagini sia verticali che orizzontali per scenari diversi.) Per indicazioni, consulta le specifiche per le immagini.
URI di riproduzione	Obbligatorio per i dispositivi mobili	Il deep link all'app del fornitore per avviare la riproduzione del video. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti
URI di riproduzione specifici della piattaforma	Facoltativo per i dispositivi mobili; obbligatorio per Google TV	Deep link specifici per la piattaforma all'app del fornitore per avviare la riproduzione del video.
Data/ora creazione	Facoltativo	In millisecondi dall'epoca.
Durata	Obbligatorio	Deve essere un valore positivo in millisecondi.
Autore	Facoltativo	Testo libero
Immagine del creator	Facoltativo	Immagine dell'avatar del creator
Numero di visualizzazioni	Facoltativo	Testo libero, deve essere localizzato.
Call to action text	Facoltativo	Testo libero da visualizzare come invito all'azione.
Tag	Facoltativo	Elenco di tag associati all'entità.
Tipo di Cosa guardare	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e deve essere uno dei seguenti quattro tipi: CONTINUE: l'utente ha già guardato più di 1 minuto di questo contenuto. NEW: l'utente ha guardato tutti gli episodi disponibili di alcuni contenuti a puntate, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i contenuti a puntate, come i programmi TV o le partite di calcio registrate di una serie. NEXT: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimangono ancora più di un episodio o esattamente un episodio in cui l'ultimo episodio non è "NEW" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti a episodi. WATCHLIST: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in un secondo momento.
Ora ultimo coinvolgimento	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi dall'epoca.
Data/ora ultima posizione di riproduzione	Obbligatorio condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster Continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca.

Specifiche per le immagini

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

Formati file

PNG, JPG, GIF statico, WebP

Dimensioni massime del file

5120 kB

Altri consigli

• Area di sicurezza per l'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)
    .setCallToActionText("Watch Now")
    .addTag("Action")
    .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)
                  .setCallToActionText("Watch Now")
                  .addTag("Action")
                  .build();

Passaggio 2: fornisci i dati del cluster

Ti consigliamo di eseguire il job di pubblicazione dei contenuti in background (ad esempio utilizzando WorkManager) e di pianificarlo regolarmente o in base a un evento (ad esempio ogni volta che l'utente apre l'app o quando ha appena aggiunto un articolo al carrello).

AppEngagePublishClient è responsabile dei cluster publisher. 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.

Per l'SDK Engage v1.6.0 e versioni successive (consigliato)

Competenze Android

Visualizza su GitHub

Integrazione dell'SDK Engage

Per installare lo skill dalla CLI Android, esegui:

android skills add engage-sdk-integration

Se il tuo team utilizza strumenti di programmazione AI (come Gemini in Android Studio), puoi automatizzare questa migrazione chiedendo all'assistente AI:

Use the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.

Puoi verificare la disponibilità del servizio per ogni tipo di cluster che intendi pubblicare. L'API isServiceAvailable accetta un oggetto di richiesta, ServiceAvailabilityRequest, che contiene i tipi di cluster per i quali deve essere verificata la disponibilità del servizio. Puoi trovare i valori enum ClusterType richiesti per ServiceAvailabilityRequest nella tabella seguente.

Tipo di cluster	Costante del tipo di cluster	Valore intero
Sconosciuto	TYPE_UNKNOWN	0
Cluster di suggerimenti	TYPE_RECOMMENDATION	1
Cluster in primo piano	TYPE_FEATURED	2
Cluster di continuazione	TYPE_CONTINUATION	3
Cluster di gestione utenti	TYPE_ENGAGEMENT	8
Cluster di sottoscrizione	TYPE_SUBSCRIPTION	12

Kotlin

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

Java

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
});

Funzionalità di disponibilità del servizio condizionale

Alcune app integrate richiedono una configurazione speciale che attiva e disattiva il servizio Engage in modo intermittente per ridurre i costi di pubblicazione. Tuttavia, questa strategia di importazione di contenuti intermittente influisce negativamente sull'esperienza utente: i contenuti obsoleti non verranno presentati e alcune piattaforme non verranno pubblicate.

A partire dalla versione 1.6.0, l'SDK Engage consente di verificare la disponibilità di tipi di cluster specifici. Se la tua app utilizza l'importazione intermittente:

• I cluster di continuazione (come Continua a guardare) rimangono attivi per impostazione predefinita su tutti i dispositivi supportati.
• Altri tipi di cluster (come i suggerimenti) vengono attivati e disattivati a intermittenza.

Se questa configurazione predefinita non è adatta alle tue esigenze, contatta [e-mail].

Per le versioni dell'SDK precedenti alla 1.6.0 (ritirate)

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.
    }
});

Nota: ti consigliamo vivamente di mantenere in esecuzione un job periodico per verificare se il servizio diventa disponibile in un secondo momento. La disponibilità del servizio potrebbe cambiare con gli upgrade della versione di Android, gli upgrade, le installazioni e le disinstallazioni delle app. Garantendo controlli periodici dei job a un determinato intervallo di tempo, i dati possono essere pubblicati una volta che il servizio diventa disponibile.

publishRecommendationClusters

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

Importante: le API di pubblicazione sono API di upsert, ovvero sostituiscono i contenuti esistenti. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, in quanto le API di pubblicazione lo fanno intrinsecamente.

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, vengono eseguite le seguenti azioni all'interno di una transazione:

• I dati RecommendationCluster esistenti del partner sviluppatore vengono 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.

Importante: le API di pubblicazione sono API di upsert, ovvero sostituiscono i contenuti esistenti. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, in quanto le API di pubblicazione lo fanno intrinsecamente.

Kotlin

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

Java

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

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

• I dati FeaturedCluster esistenti del partner sviluppatore vengono 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.

Importante: le API di pubblicazione sono API di upsert, ovvero sostituiscono i contenuti esistenti. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, in quanto le API di pubblicazione lo fanno intrinsecamente.

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, vengono eseguite le seguenti azioni all'interno di una transazione:

• I dati ContinuationCluster esistenti del partner sviluppatore vengono 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 tessera di accesso . L'azione di accesso indirizza gli utenti alla pagina di accesso dell'app in modo che l'app possa pubblicare contenuti (o fornire contenuti più personalizzati)

I seguenti metadati fanno parte della scheda di accesso:

Attributo	Requisito	Descrizione
URI azione	Obbligatorio	Deep link all'azione (ad es. rimanda alla pagina di accesso all'app)
Immagine	Facoltativo. Se non viene fornito, è necessario fornire il titolo	Immagine mostrata sulla scheda Immagini con proporzioni 16:9 e risoluzione di 1264 x 712
Titolo	Facoltativo. Se non viene fornito, è necessario fornire l'immagine	Titolo sulla scheda
Testo di azione	Facoltativo	Testo mostrato nella CTA (ad es. Accedi)
Sottotitolo	Facoltativo	Sottotitolo facoltativo sulla scheda

Importante: le API di pubblicazione sono API di upsert, ovvero sostituiscono i contenuti esistenti. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, in quanto le API di pubblicazione lo fanno intrinsecamente.

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, vengono eseguite le seguenti azioni all'interno di una transazione:

• I dati UserAccountManagementCluster esistenti del partner sviluppatore 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 non viene pubblicato nessuno dei cluster, ti consigliamo vivamente di aggiornare lo stato di pubblicazione utilizzando l'API updatePublishStatus. Questo è importante perché :

• Fornire lo stato in tutti gli scenari, anche quando i contenuti sono pubblicati (STATUS == PUBLISHED), è fondamentale per compilare le dashboard che utilizzano questo stato esplicito per comunicare l'integrità e altre metriche della tua integrazione.
• Se non vengono pubblicati contenuti, ma lo stato dell'integrazione non è interrotto (STATUS == NOT_PUBLISHED), Google può evitare di attivare avvisi nelle dashboard di integrità dell'app. Conferma che i contenuti non vengono pubblicati a causa di una situazione prevista dal punto di vista del fornitore.
• Aiuta gli sviluppatori a fornire informazioni su quando i dati vengono pubblicati e quando no.
• Google potrebbe utilizzare i codici di stato per invitare l'utente a eseguire determinate azioni nell'app in modo che possa visualizzare i contenuti dell'app o superare il problema.

L'elenco dei codici di stato di pubblicazione idonei è il seguente :

// 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 Accedi. Se per qualsiasi motivo i fornitori non sono in grado di pubblicare la scheda di accesso, consigliamo di chiamare l'API updatePublishStatus con il codice di stato NOT_PUBLISHED_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());

deleteRecommendationsClusters

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

Importante: le API di eliminazione devono essere chiamate solo quando non sono presenti contenuti da pubblicare. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta [e-mail] prima di utilizzare le API di eliminazione.

Kotlin

client.deleteRecommendationsClusters()

Java

client.deleteRecommendationsClusters();

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

Nota: questa API è disponibile dalla versione 1.1.0 in poi.

deleteFeaturedCluster

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

Importante: le API di eliminazione devono essere chiamate solo quando non sono presenti contenuti da pubblicare. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta [e-mail] prima di utilizzare le API di eliminazione.

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.

Nota: questa API è disponibile dalla versione 1.1.0 in poi.

deleteContinuationCluster

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

Importante: le API di eliminazione devono essere chiamate solo quando non sono presenti contenuti da pubblicare. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta [e-mail] prima di utilizzare le API di eliminazione.

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.

Nota: questa API è disponibile dalla versione 1.1.0 in poi.

deleteUserManagementCluster

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

Importante: le API di eliminazione devono essere chiamate solo quando non sono presenti contenuti da pubblicare. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta [e-mail] prima di utilizzare le API di eliminazione.

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.

Nota: questa API è disponibile dalla versione 1.1.0 in poi.

deleteClusters

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

Importante: le API di eliminazione devono essere chiamate solo quando non sono presenti contenuti da pubblicare. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta [e-mail] prima di utilizzare le API di eliminazione.

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 da poter intraprendere 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 con la causa inclusa come codice di errore.

Codice di errore	Nome errore	Nota
1	SERVICE_NOT_FOUND	Il servizio non è disponibile sul dispositivo specificato.
2	SERVICE_NOT_AVAILABLE	Il servizio è disponibile sul dispositivo specificato, ma non è disponibile al momento della chiamata (ad esempio, è disattivato esplicitamente).
3	SERVICE_CALL_EXECUTION_FAILURE	L'esecuzione dell'attività non è riuscita a causa di problemi di threading. In questo caso, è possibile riprovare.
4	SERVICE_CALL_PERMISSION_DENIED	Il chiamante non è autorizzato a effettuare la chiamata di servizio.
5	SERVICE_CALL_INVALID_ARGUMENT	La richiesta contiene dati non validi (ad esempio, un numero di cluster superiore a quello consentito).
6	SERVICE_CALL_INTERNAL	Si è verificato un errore lato servizio.
7	SERVICE_CALL_RESOURCE_EXHAUSTED	La chiamata di servizio viene effettuata troppo di frequente.

Passaggio 3: gestisci gli intent di trasmissione

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

L'obiettivo degli intent di trasmissione è principalmente la riattivazione dell'app e la sincronizzazione forzata dei dati. Gli intent di trasmissione non sono progettati per essere inviati molto di frequente. Viene attivato solo quando l'Engage Service determina che i contenuti potrebbero essere obsoleti (ad esempio, risalenti a una settimana prima). In questo modo, è più probabile che l'utente possa usufruire di un'esperienza con contenuti aggiornati, anche se l'applicazione non è stata eseguita per un lungo periodo di tempo.

BroadcastReceiver deve essere configurato nei seguenti due modi:

• Registra dinamicamente un'istanza della classe BroadcastReceiver utilizzando Context.registerReceiver(). In questo modo, le applicazioni ancora attive in memoria possono comunicare.

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),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

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),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

}

• Dichiara staticamente un'implementazione con il tag <receiver> nel file AndroidManifest.xml. In questo modo, l'applicazione può ricevere intent di trasmissione quando non è in esecuzione e può anche pubblicare i contenuti.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      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 Quando ricevi questo intent, ti consigliamo di avviare una chiamata publishFeaturedCluster.
• com.google.android.engage.action.PUBLISH_CONTINUATION Ti consigliamo di avviare una chiamata publishContinuationCluster quando ricevi questo intent.

Workflow di integrazione

Per una guida passo passo sulla verifica dell'integrazione una volta completata, consulta il flusso di lavoro di integrazione per gli sviluppatori di Engage.

Domande frequenti

Per le domande frequenti, consulta Domande frequenti sull'SDK Engage.

Contatto

Contatta [e-mail] in caso di domande durante il processo di integrazione.

Passaggi successivi

Dopo aver completato questa integrazione, i passaggi successivi sono i seguenti:

• Invia un'email all'indirizzo [e-mail] e allega l'APK integrato pronto per essere testato da Google.
• Google esegue una verifica e dei controlli interni per assicurarsi che l'integrazione funzioni come previsto. Se sono necessarie modifiche, Google ti contatterà con tutti i dettagli necessari.
• Al termine dei test, se non sono necessarie modifiche, Google ti contatta per informarti che puoi iniziare a pubblicare l'APK aggiornato e integrato sul Play Store.
• Dopo che Google avrà confermato che l'APK aggiornato è stato pubblicato sul Play Store, i cluster Contenuti consigliati, In evidenza e Continua potrebbero essere pubblicati e visibili agli utenti.