Aumenta il coinvolgimento con l'app raggiungendo gli utenti ovunque si trovino. Integra l'SDK Engage per pubblicare contenuti della sezione Continua a guardare e consigli personalizzati direttamente sugli utenti su più piattaforme on-device, tra cui Google TV, Raccolte, Entertainment Space e il Play Store. L'integrazione aggiunge meno di 50 KB (compressi) all'APK medio e richiede alla maggior parte delle app circa una settimana di tempo di sviluppo. Scopri di più sul nostro sito aziendale.
Questa guida contiene istruzioni per gli sviluppatori partner per integrare i propri contenuti video utilizzando l'SDK Engage per compilare sia questa nuova piattaforma sia le piattaforme Google esistenti.
Dettaglio dell'integrazione
Terminologia
Questa integrazione include i seguenti tre tipi di cluster: Consiglio, Continuazione e In primo piano.
I cluster di consigli mostrano suggerimenti personalizzati sui contenuti da guardare di un singolo sviluppatore partner.
I consigli hanno la seguente struttura:
Cluster di consigli:una visualizzazione dell'interfaccia utente che contiene un gruppo di consigli dello stesso sviluppatore partner.
Figura 1. Interfaccia utente 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 Fornire 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 del cluster di consigli di un singolo partner.
Il cluster Continuazione mostra i video incompleti e le puntate appena pubblicate pertinenti di più sviluppatori partner in un unico raggruppamento dell'interfaccia utente. Ogni sviluppatore partner potrà trasmettere un massimo di 10 entità nel cluster di continuazione. Alcuni studi hanno dimostrato che i consigli personalizzati insieme ai contenuti di continuazione personalizzati generano il coinvolgimento migliore degli utenti.
Figura 3. Interfaccia utente di Entertainment Space che mostra un cluster di continuazione con consigli incompleti di più partner (al momento è visibile un solo consiglio). Il cluster In primo piano mostra una selezione di entità di più sviluppatori partner in un unico raggruppamento dell'interfaccia utente. Verrà visualizzato un singolo cluster in primo piano, che viene mostrato nella parte superiore dell'interfaccia utente con un posizionamento prioritario sopra tutti i cluster di consigli. Ogni sviluppatore partner potrà trasmettere fino a 10 entità nel cluster In primo piano.
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 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 ulteriori informazioni, consulta la sezione Visibilità dei pacchetti in Android 11.
Riepilogo
Il design si basa su un'implementazione di un servizio vincolato.
I dati che un cliente può pubblicare sono soggetti ai seguenti limiti per i diversi tipi di cluster:
Tipo di cluster | Limiti del cluster | Limiti massimi di entità in un cluster |
---|---|---|
Cluster di consigli | 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 |
Passaggio 0: migrazione dall'integrazione esistente dell'SDK Media Home
Mappa i modelli di dati dall'integrazione esistente
Se esegui la migrazione da un'integrazione di Media Home esistente, la tabella seguente illustra come mappare i modelli di dati negli SDK esistenti al nuovo SDK Engage:
Integrazione MediaHomeVideoContract equivalente | Integrazione dell'SDK Engage equivalente |
---|---|
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 |
Suddivise in classi separate: EventVideo ,
LiveStreamingVideo , Movie ,
TvEpisode , TvSeason , TvShow ,
VideoClipEntity
|
com.google.android.mediahome.video.PreviewProgram.Builder
|
Suddivisi in costruttori 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 |
Suddivisi 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 |
Cluster di pubblicazione nell'SDK Media Home e nell'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à 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 delle entità
L'SDK ha definito entità diverse per rappresentare ogni tipo di elemento. Supportiamo le seguenti entità per la categoria Guarda:
Il seguente grafico illustra gli attributi e i requisiti per ogni tipo.
MovieEntity
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | |
Immagini dei poster | Obbligatorio | È richiesta almeno un'immagine, che deve avere proporzioni. (è preferibile l'orientamento orizzontale, ma è consigliabile passare sia immagini verticali che orizzontali per scenari diversi).
Per indicazioni, consulta le specifiche per le immagini. |
URI di riproduzione | Obbligatorio |
Il link diretto all'app del fornitore per avviare la riproduzione del film. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente |
URI pagina informativa | Facoltativo |
Il link diretto all'app del fornitore per mostrare i dettagli del film. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente |
Data di uscita | Facoltativo | In millisecondi dall'epoca. |
Disponibilità | Obbligatorio | DISPONIBILE: i contenuti sono disponibili per l'utente senza alcuna ulteriore azione. 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. ACQUISTATO: i contenuti sono stati acquistati o noleggiati dall'utente. |
Prezzo dell'offerta | Facoltativo | Testo libero |
Durata | Obbligatorio | In millisecondi. |
Genere | Obbligatorio | Testo libero |
Classificazioni dei contenuti | Facoltativo | Testo libero, rispetta lo standard di settore. (Esempio) |
Tipo di Guarda successivo | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei seguenti quattro tipi: 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 è stata resa disponibile una nuova puntata ed esiste esattamente una puntata non guardata. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVA: l'utente ha guardato una o più puntate complete di alcuni contenuti episodici, ma rimangono più puntate o esattamente una puntata, dove l'ultima puntata non è "NUOVA" ed è stata rilasciata prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per organizzare manualmente i contenuti che vuole guardare in seguito. |
Ora dell'ultimo coinvolgimento | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster Continuità. In epoch millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca. |
TvShowEntity
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | |
Immagini dei poster | Obbligatorio | È richiesta almeno un'immagine, che deve avere proporzioni. (è preferibile l'orientamento orizzontale, ma è consigliabile passare sia immagini verticali che orizzontali per scenari diversi).
Per indicazioni, consulta le specifiche per le immagini. |
URI pagina informativa | Obbligatorio |
Il link diretto all'app del fornitore per mostrare i dettagli del programma TV. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente |
URI di riproduzione | Facoltativo |
Il link diretto all'app del fornitore per avviare la riproduzione del programma TV. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente |
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à | Obbligatorio | DISPONIBILE: i contenuti sono disponibili per l'utente senza alcuna ulteriore azione. 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. ACQUISTATO: i contenuti sono stati acquistati o noleggiati dall'utente. |
Prezzo dell'offerta | Facoltativo | Testo libero |
Conteggio stagioni | Obbligatorio | Intero positivo |
Genere | Obbligatorio | Testo libero |
Classificazioni dei contenuti | Facoltativo | Testo libero, rispetta lo standard di settore. (Esempio) |
Tipo di Guarda successivo | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei seguenti quattro tipi: 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 è stata resa disponibile una nuova puntata ed esiste esattamente una puntata non guardata. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVA: l'utente ha guardato una o più puntate complete di alcuni contenuti episodici, ma rimangono più puntate o esattamente una puntata, dove l'ultima puntata non è "NUOVA" ed è stata rilasciata prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per organizzare manualmente i contenuti che vuole guardare in seguito. |
Ora dell'ultimo coinvolgimento | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster Continuità. In epoch millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca. |
TvSeasonEntity
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | |
Immagini dei poster | Obbligatorio | È richiesta almeno un'immagine, che deve avere proporzioni. (è preferibile l'orientamento orizzontale, ma è consigliabile passare sia immagini verticali che orizzontali per scenari diversi).
Per indicazioni, consulta le specifiche per le immagini. |
URI pagina informativa | Obbligatorio |
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 questa domanda frequente |
URI di riproduzione | Facoltativo |
Il link diretto all'app del fornitore per avviare la riproduzione della stagione del programma TV. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente |
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à | Obbligatorio | DISPONIBILE: i contenuti sono disponibili per l'utente senza alcuna ulteriore azione. 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. ACQUISTATO: i contenuti sono stati acquistati o noleggiati dall'utente. |
Prezzo dell'offerta | Facoltativo | Testo libero |
Numero di puntate | Obbligatorio | Intero positivo |
Genere | Obbligatorio | Testo libero |
Classificazioni dei contenuti | Facoltativo | Testo libero, rispetta lo standard di settore. (Esempio) |
Tipo di Guarda successivo | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei seguenti quattro tipi: 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 è stata resa disponibile una nuova puntata ed esiste esattamente una puntata non guardata. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVA: l'utente ha guardato una o più puntate complete di alcuni contenuti episodici, ma rimangono più puntate o esattamente una puntata, dove l'ultima puntata non è "NUOVA" ed è stata rilasciata prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per organizzare manualmente i contenuti che vuole guardare in seguito. |
Ora dell'ultimo coinvolgimento | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster Continuità. In epoch millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca. |
TvEpisodeEntity
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | |
Immagini dei poster | Obbligatorio | È richiesta almeno un'immagine, che deve avere proporzioni. (è preferibile l'orientamento orizzontale, ma è consigliabile passare sia immagini verticali che orizzontali per scenari diversi).
Per indicazioni, consulta le specifiche per le immagini. |
URI di riproduzione | Obbligatorio |
Il link diretto all'app del fornitore per avviare la riproduzione della puntata. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente |
URI pagina informativa | Facoltativo |
Il link diretto all'app del fornitore per mostrare i dettagli della puntata del programma TV. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente |
Mostra il numero della puntata |
Facoltativo Disponibile nella versione 1.3.1 |
Stringa |
Data messa in onda | Obbligatorio | In millisecondi dall'epoca. |
Disponibilità | Obbligatorio | DISPONIBILE: i contenuti sono disponibili per l'utente senza alcuna ulteriore azione. 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. ACQUISTATO: i contenuti sono stati acquistati o noleggiati dall'utente. |
Prezzo dell'offerta | Facoltativo | Testo libero |
Durata | Obbligatorio | Deve essere un valore positivo in millisecondi. |
Genere | Obbligatorio | Testo libero |
Classificazioni dei contenuti | Facoltativo | Testo libero, rispetta lo standard di settore. (Esempio) |
Tipo di Guarda successivo | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei seguenti quattro tipi: 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 è stata resa disponibile una nuova puntata ed esiste esattamente una puntata non guardata. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVA: l'utente ha guardato una o più puntate complete di alcuni contenuti episodici, ma rimangono più puntate o esattamente una puntata, dove l'ultima puntata non è "NUOVA" ed è stata rilasciata prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per organizzare manualmente i contenuti che vuole guardare in seguito. |
Ora dell'ultimo coinvolgimento | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster Continuità. In epoch millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è CONTINUE. In millisecondi dall'epoca. |
LiveStreamingVideoEntity
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | |
Immagini dei poster | Obbligatorio | È richiesta almeno un'immagine, che deve avere proporzioni. (è preferibile l'orientamento orizzontale, ma è consigliabile passare sia immagini verticali che orizzontali per scenari diversi).
Per indicazioni, consulta le specifiche per le immagini. |
URI di riproduzione | Obbligatorio |
Il link diretto all'app del fornitore per avviare la riproduzione del video. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente |
Emittente | Obbligatorio | 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. |
Tipo di Guarda successivo | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei seguenti quattro tipi: 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 è stata resa disponibile una nuova puntata ed esiste esattamente una puntata non guardata. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVA: l'utente ha guardato una o più puntate complete di alcuni contenuti episodici, ma rimangono più puntate o esattamente una puntata, dove l'ultima puntata non è "NUOVA" ed è stata rilasciata prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per organizzare manualmente i contenuti che vuole guardare in seguito. |
Ora dell'ultimo coinvolgimento | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster Continuità. In epoch millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di 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 dei poster | Obbligatorio | È richiesta almeno un'immagine, che deve avere proporzioni. (è preferibile l'orientamento orizzontale, ma è consigliabile passare sia immagini verticali che orizzontali per scenari diversi).
Per indicazioni, consulta le specifiche per le immagini. |
URI di riproduzione | Obbligatorio |
Il link diretto all'app del fornitore per avviare la riproduzione del video. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente |
Data e ora di creazione | Obbligatorio | In millisecondi dall'epoca. |
Durata | Obbligatorio | Deve essere un valore positivo in millisecondi. |
Creator | Obbligatorio | Testo libero |
Immagine del creator | Facoltativo | Immagine dell'avatar del creator |
Numero di visualizzazioni | Facoltativo | Testo libero, deve essere localizzato. |
Tipo di Guarda successivo | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e deve essere uno dei seguenti quattro tipi: 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 è stata resa disponibile una nuova puntata ed esiste esattamente una puntata non guardata. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVA: l'utente ha guardato una o più puntate complete di alcuni contenuti episodici, ma rimangono più puntate o esattamente una puntata, dove l'ultima puntata non è "NUOVA" ed è stata rilasciata prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha scelto esplicitamente di aggiungere un film, un evento o una serie a una lista di titoli per organizzare manualmente i contenuti che vuole guardare in seguito. |
Ora dell'ultimo coinvolgimento | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster Continuità. In epoch millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatorio condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di 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
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
Ti consigliamo di eseguire il job di pubblicazione dei contenuti in background (ad esempio utilizzando WorkManager) e di pianificarlo su base regolare o in base a un evento (ad esempio ogni volta che l'utente apre l'app o quando l'utente ha appena aggiunto un articolo 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, 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 consigli 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, 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
.
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 scheda Accedi . 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 Accedi:
Attributo | Requisito | Descrizione |
---|---|---|
URI azione | Obbligatorio | Link diretto all'azione (ad es. alla pagina di accesso all'app) |
Immagine | (Facoltativo) Se non viene fornito, deve essere fornito il titolo |
Immagine mostrata sulla scheda Immagini con proporzioni 16 x 9 e una risoluzione di 1264 x 712 |
Titolo | Facoltativo: se non viene fornito, deve essere fornita l'immagine | Nome sulla carta |
Testo dell'azione | Facoltativo | Testo visualizzato nell'invito all'azione (ad es. Accedi) |
Sottotitolo | Facoltativo | Sottotitolo facoltativo nella 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, 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 aggiornato UserAccountManagementCluster.
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 è pubblicato, 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 trasmettere l'integrità e altre metriche dell'integrazione.
- Se non vengono pubblicati contenuti, ma lo stato dell'integrazione non è in errore (STATUS == NOT_PUBLISHED), Google può evitare di attivare gli avvisi nelle dashboard di salute dell'app. Conferma che i contenuti non vengono pubblicati a causa di una situazione prevedibile dal punto di vista del fornitore.
- Aiuta gli sviluppatori a fornire informazioni su quando i dati vengono pubblicati o meno.
- Google potrebbe utilizzare i codici di stato per indurre l'utente a eseguire determinate azioni nell'app in modo da poter vedere i contenuti dell'app o superarli.
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 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());
deleteRecommendationClusters
Questa API viene utilizzata per eliminare i contenuti dei cluster di consigli.
Kotlin
client.deleteRecommendationClusters()
Java
client.deleteRecommendationClusters();
Quando il servizio riceve la richiesta, rimuove i dati esistenti dai gruppi di consigli. 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 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 dell'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 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 eseguire nuovamente il tentativo. |
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, più del numero consentito di cluster). |
6 |
SERVICE_CALL_INTERNAL |
Si è verificato un errore lato servizio. |
7 |
SERVICE_CALL_RESOURCE_EXHAUSTED |
La chiamata al servizio viene effettuata troppo di frequente. |
Passaggio 3: gestisci gli intent di trasmissione
Oltre a effettuare chiamate API di pubblicazione dei contenuti tramite un job, è necessario anche configurare un BroadcastReceiver
per ricevere la richiesta di pubblicazione dei contenuti.
Lo scopo degli intent di trasmissione è principalmente la riattivazione dell'app e l'applicazione forzata della sincronizzazione dei dati. Gli intent di trasmissione non sono progettati per essere inviati molto di frequente. Viene attivata solo quando il servizio Engage determina che i contenuti potrebbero essere obsoleti (ad esempio, risalenti a una settimana prima). In questo modo, è più probabile che l'utente possa avere 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
utilizzandoContext.registerReceiver()
. In questo modo, viene attivata la comunicazione da applicazioni che sono 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)); }
- Dichiara in modo statico un'implementazione con il tag
<receiver>
nelAndroidManifest.xml
file. In questo modo, l'applicazione può ricevere intent di trasmissione quando non è in esecuzione e 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>
I seguenti intent vengono inviati dal servizio:
com.google.android.engage.action.PUBLISH_RECOMMENDATION
Ti consigliamo di avviare una chiamatapublishRecommendationClusters
quando ricevi questa intenzione.com.google.android.engage.action.PUBLISH_FEATURED
È consigliabile avviare una chiamatapublishFeaturedCluster
quando si riceve questo intento.com.google.android.engage.action.PUBLISH_CONTINUATION
È consigliabile avviare una chiamatapublishContinuationCluster
quando si riceve questo intento.
Flusso di lavoro di integrazione
Per una guida passo passo sulla verifica dell'integrazione al termine, consulta Flusso di lavoro di integrazione degli sviluppatori di Engage.
Domande frequenti
Consulta le Domande frequenti sull'SDK Engage per approfondire.
Contatto
Contatta engage-developers@google.com in caso di domande durante la procedura di integrazione.
Passaggi successivi
Dopo aver completato questa integrazione, i passaggi successivi sono i seguenti:
- Invia un'email all'indirizzo engage-developers@google.com e allega il tuo APK integrato pronto per i test di Google.
- Google esegue una verifica e delle revisioni interne per assicurarsi che l'integrazione funzioni come previsto. Se sono necessarie modifiche, Google ti contatterà con tutti i dettagli necessari.
- Al termine del 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 Consiglio, In evidenza e Continuazione potrebbero essere pubblicati e visibili agli utenti.