Google sta creando una piattaforma on-device che organizza le app degli utenti per verticali e offre una nuova esperienza immersiva per il consumo e la scoperta di contenuti delle app personalizzati. Questa esperienza a schermo intero offre agli sviluppatori partner l'opportunità di mostrare i loro migliori contenuti avanzati in un canale dedicato esterno alla loro app.
Questa guida contiene le istruzioni per gli sviluppatori partner per integrare i loro contenuti video utilizzando l'SDK Engage per completare sia questa nuova area di piattaforma sia le piattaforme Google esistenti.
Dettagli 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 da un singolo partner di sviluppo.
I consigli hanno la seguente struttura:
Cluster di suggerimenti:una visualizzazione dell'interfaccia utente che contiene un gruppo di suggerimenti dello stesso sviluppatore 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 dati delle entità per un elenco dei tipi di entità supportati.
Il cluster Continuation mostra i video non completati e le puntate nuove uscite pertinenti di più sviluppatori partner in un unico raggruppamento nell'interfaccia utente. Ogni partner di sviluppo potrà trasmettere un massimo di 10 entità nel cluster di continuazione. Gli studi dimostrano che i consigli personalizzati insieme ai contenuti di Continuazione personalizzati generano il coinvolgimento degli utenti migliore.
Il cluster In primo piano mostra una selezione di entità di più partner di sviluppatori in un unico raggruppamento dell'interfaccia utente. Ci sarà un singolo cluster In primo piano, visualizzato nella parte superiore dell'interfaccia utente con un posizionamento della priorità sopra tutti i cluster di suggerimenti. Ogni sviluppatore partner potrà trasmettere fino a 10 entità nel cluster in primo piano.
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.4.0'
}
Per maggiori informazioni, consulta la sezione 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 tipi di cluster diversi:
Tipo di cluster | Limiti del cluster | Limiti massimi di entità in un cluster |
---|---|---|
Cluster di suggerimenti | Massimo 5 | Massimo 50 |
Cluster di continuazione | Al massimo 1 | Massimo 10 |
Cluster in primo piano | Al massimo 1 | Massimo 10 |
Passaggio 0: migrazione dall'integrazione dell'SDK Media Home esistente
Mappa i modelli di dati dall'integrazione esistente
Se stai eseguendo la migrazione da un'integrazione Media Home esistente, la seguente tabella descrive come mappare i modelli dei dati negli SDK esistenti al nuovo SDK Engage:
Equivalente dell'integrazione di 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 |
Suddivisione in corsi separati: EventVideo ,
LiveStreamingVideo , Movie , TvEpisode ,
TvSeason , TvShow , VideoClipEntity |
com.google.android.mediahome.video.PreviewProgram.Builder |
Suddivisione in builder in classi separate: EventVideo ,
LiveStreamingVideo , Movie , TvEpisode ,
TvSeason , TvShow , VideoClipEntity |
com.google.android.mediahome.video.VideoContract |
Non serve più. |
com.google.android.mediahome.video.WatchNextProgram |
Suddivisione in attributi in classi separate:
EventVideoEntity , LiveStreamingVideoEntity ,
MovieEntity , TvEpisodeEntity ,
TvSeasonEntity , TvShowEntity ,
VideoClipEntity |
com.google.android.mediahome.video.WatchNextProgram.Builder |
Suddivisione in attributi in classi separate:
EventVideoEntity , LiveStreamingVideoEntity ,
MovieEntity , TvEpisodeEntity ,
TvSeasonEntity , TvShowEntity ,
VideoClipEntity |
Pubblicazione di cluster nell'SDK Media Home e nell'SDK Engage
Con l'SDK Media Home, i cluster e le entità sono stati pubblicati tramite API separate:
// 1. Fetch existing channels
List<PreviewChannel> channels = PreviewChannelHelper.getAllChannels();
// 2. If there are no channels, publish new channels
long channelId = PreviewChannelHelper.publishChannel(builder.build());
// 3. If there are existing channels, decide whether to update channel contents
PreviewChannelHelper.updatePreviewChannel(channelId, builder.build());
// 4. Delete all programs in the channel
PreviewChannelHelper.deleteAllPreviewProgramsByChannelId(channelId);
// 5. publish new programs in the channel
PreviewChannelHelper.publishPreviewProgram(builder.build());
Con l'SDK Engage, la pubblicazione di cluster ed entità viene combinata in un'unica chiamata API. Tutte le entità che appartengono a un cluster vengono pubblicate con 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 dell'entità
L'SDK ha definito diverse entità per rappresentare ogni tipo di elemento. Per la categoria Guarda, vengono supportate le seguenti entità:
Il seguente grafico illustra gli attributi e i requisiti per ciascun tipo.
MovieEntity
Attributo | Requisito | Notes |
---|---|---|
Nome | Obbligatorie | |
Immagini poster | Obbligatorie | È richiesta almeno un'immagine, che deve essere fornita con proporzioni. È preferibile utilizzare l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi.
Per istruzioni, consulta la sezione Specifiche delle immagini. |
URI di riproduzione | Obbligatorie |
Il link diretto all'app del fornitore per iniziare la riproduzione del film. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
URI pagina informazioni | Facoltativo |
Il link diretto all'app del fornitore per mostrare i dettagli del film. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Data di uscita | Obbligatorie | In millisecondi dell'epoca. |
Disponibilità | Obbligatorie | AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni. FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente acquista un abbonamento. PAID_CONTENT: i contenuti richiedono l'acquisto o il noleggio da parte dell'utente. ACQUISTI: i contenuti sono stati acquistati o noleggiati dall'utente. |
Prezzo dell'offerta | Facoltativo | Testo libero |
Durata | Obbligatorie | In millisecondi. |
Genere | Obbligatorie | Testo libero |
Classificazioni dei contenuti | Obbligatorie | Testo libero, segui lo standard di settore. (Esempio) |
Tipo di video da guardare successivo | Obbligatoria 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 a episodi, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimane più di un episodio o rimane esattamente un episodio in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha esplicitamente scelto di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in seguito. |
Data/ora ultimo coinvolgimento | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è impostato su CONTINUA. In millisecondi dell'epoca. |
TvShowEntity
Attributo | Requisito | Notes |
---|---|---|
Nome | Obbligatorie | |
Immagini poster | Obbligatorie | È richiesta almeno un'immagine, che deve essere fornita con proporzioni. È preferibile utilizzare l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi.
Per istruzioni, consulta la sezione Specifiche delle immagini. |
URI pagina informazioni | Obbligatorie |
Il link diretto all'app del fornitore per mostrare i dettagli del programma TV. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
URI di riproduzione | Facoltativo |
Il link diretto all'app del fornitore per iniziare a riprodurre il programma TV. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Data di messa in onda del primo episodio | Obbligatorie | In millisecondi dell'epoca. |
Data di messa in onda dell'ultima puntata | Facoltativo | In millisecondi dell'epoca. |
Disponibilità | Obbligatorie | AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni. FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente acquista un abbonamento. PAID_CONTENT: i contenuti richiedono l'acquisto o il noleggio da parte dell'utente. ACQUISTI: i contenuti sono stati acquistati o noleggiati dall'utente. |
Prezzo dell'offerta | Facoltativo | Testo libero |
Conteggio stagioni | Obbligatorie | Intero positivo |
Genere | Obbligatorie | Testo libero |
Classificazioni dei contenuti | Obbligatorie | Testo libero, segui lo standard di settore. (Esempio) |
Tipo di video da guardare successivo | Obbligatoria 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 a episodi, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimane più di un episodio o rimane esattamente un episodio in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha esplicitamente scelto di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in seguito. |
Data/ora ultimo coinvolgimento | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è impostato su CONTINUA. In millisecondi dell'epoca. |
TvSeasonEntity
Attributo | Requisito | Notes |
---|---|---|
Nome | Obbligatorie | |
Immagini poster | Obbligatorie | È richiesta almeno un'immagine, che deve essere fornita con proporzioni. È preferibile utilizzare l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi.
Per istruzioni, consulta la sezione Specifiche delle immagini. |
URI pagina informazioni | Obbligatorie |
Il link diretto all'app del fornitore per mostrare i dettagli della stagione del programma TV. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
URI di riproduzione | Facoltativo |
Il link diretto all'app del fornitore per iniziare a riprodurre la stagione del programma TV. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Mostra numero stagione |
Facoltativo Disponibile nella versione 1.3.1 |
Stringa |
Data di messa in onda del primo episodio | Obbligatorie | In millisecondi dell'epoca. |
Data di messa in onda dell'ultima puntata | Facoltativo | In millisecondi dell'epoca. |
Disponibilità | Obbligatorie | AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni. FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente acquista un abbonamento. PAID_CONTENT: i contenuti richiedono l'acquisto o il noleggio da parte dell'utente. ACQUISTI: i contenuti sono stati acquistati o noleggiati dall'utente. |
Prezzo dell'offerta | Facoltativo | Testo libero |
Numero di puntate | Obbligatorie | Intero positivo |
Genere | Obbligatorie | Testo libero |
Classificazioni dei contenuti | Obbligatorie | Testo libero, segui lo standard di settore. (Esempio) |
Tipo di video da guardare successivo | Obbligatoria 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 a episodi, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimane più di un episodio o rimane esattamente un episodio in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha esplicitamente scelto di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in seguito. |
Data/ora ultimo coinvolgimento | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è impostato su CONTINUA. In millisecondi dell'epoca. |
TvEpisodeEntity
Attributo | Requisito | Notes |
---|---|---|
Nome | Obbligatorie | |
Immagini poster | Obbligatorie | È richiesta almeno un'immagine, che deve essere fornita con proporzioni. È preferibile utilizzare l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi.
Per istruzioni, consulta la sezione Specifiche delle immagini. |
URI di riproduzione | Obbligatorie |
Il link diretto all'app del fornitore per iniziare la riproduzione della puntata. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
URI pagina informazioni | Facoltativo |
Il link diretto all'app del provider per mostrare i dettagli dell'episodio del programma TV. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Visualizza numero puntata |
Facoltativo Disponibile nella versione 1.3.1 |
Stringa |
Data messa in onda | Obbligatorie | In millisecondi dell'epoca. |
Disponibilità | Obbligatorie | AVAILABLE: i contenuti sono disponibili per l'utente senza ulteriori azioni. FREE_WITH_SUBSCRIPTION: i contenuti sono disponibili dopo che l'utente acquista un abbonamento. PAID_CONTENT: i contenuti richiedono l'acquisto o il noleggio da parte dell'utente. ACQUISTI: i contenuti sono stati acquistati o noleggiati dall'utente. |
Prezzo dell'offerta | Facoltativo | Testo libero |
Durata | Obbligatorie | Deve essere un valore positivo in millisecondi. |
Genere | Obbligatorie | Testo libero |
Classificazioni dei contenuti | Obbligatorie | Testo libero, segui lo standard di settore. (Esempio) |
Tipo di video da guardare successivo | Obbligatoria 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 a episodi, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimane più di un episodio o rimane esattamente un episodio in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha esplicitamente scelto di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in seguito. |
Data/ora ultimo coinvolgimento | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è impostato su CONTINUA. In millisecondi dell'epoca. |
LiveStreamingVideoEntity
Attributo | Requisito | Notes |
---|---|---|
Nome | Obbligatorie | |
Immagini poster | Obbligatorie | È richiesta almeno un'immagine, che deve essere fornita con proporzioni. È preferibile utilizzare l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi.
Per istruzioni, consulta la sezione Specifiche delle immagini. |
URI di riproduzione | Obbligatorie |
Il link diretto all'app del fornitore per avviare la riproduzione del video. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Emittente | Obbligatorie | Testo libero |
Ora di inizio | Facoltativo | In millisecondi dell'epoca. |
Ora di fine | Facoltativo | In millisecondi dell'epoca. |
Numero di visualizzazioni | Facoltativo | Testo libero, deve essere localizzato. |
Tipo di video da guardare successivo | Obbligatoria 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 a episodi, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimane più di un episodio o rimane esattamente un episodio in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha esplicitamente scelto di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in seguito. |
Data/ora ultimo coinvolgimento | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è impostato su CONTINUA. In millisecondi dell'epoca. |
VideoClipEntity
L'oggetto VideoClipEntity
rappresenta un'entità video proveniente dai social media,
come TikTok o YouTube.
Attributo | Requisito | Notes |
---|---|---|
Nome | Obbligatorie | |
Immagini poster | Obbligatorie | È richiesta almeno un'immagine, che deve essere fornita con proporzioni. È preferibile utilizzare l'orientamento orizzontale, ma è consigliabile trasferire immagini sia verticali sia orizzontali per scenari diversi.
Per istruzioni, consulta la sezione Specifiche delle immagini. |
URI di riproduzione | Obbligatorie |
Il link diretto all'app del fornitore per avviare la riproduzione del video. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Data e ora di creazione | Obbligatorie | In millisecondi dell'epoca. |
Durata | Obbligatorie | Deve essere un valore positivo in millisecondi. |
Creatore | Obbligatorie | Testo libero |
Immagine autore | Facoltativo | Immagine dell'avatar del creator |
Numero di visualizzazioni | Facoltativo | Testo libero, deve essere localizzato. |
Tipo di video da guardare successivo | Obbligatoria 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 a episodi, ma è diventato disponibile un nuovo episodio e c'è esattamente un episodio non guardato. Questo vale per i programmi TV, le partite di calcio registrate in una serie e così via. SUCCESSIVO: l'utente ha guardato uno o più episodi completi di alcuni contenuti a episodi, ma rimane più di un episodio o rimane esattamente un episodio in cui l'ultimo episodio non è "NUOVO" ed è stato pubblicato prima che l'utente iniziasse a guardare i contenuti episodici. LISTA DI TITOLI: l'utente ha esplicitamente scelto di aggiungere un film, un evento o una serie a una lista di titoli per selezionare manualmente i contenuti che vuole guardare in seguito. |
Data/ora ultimo coinvolgimento | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi. |
Ora dell'ultima posizione di riproduzione | Obbligatoria condizionalmente | Deve essere fornito quando l'elemento si trova nel cluster di continuazione e WatchNextType è impostato su CONTINUA. In millisecondi dell'epoca. |
Specifiche per le immagini
Nella sezione seguente sono elencate le specifiche richieste per gli asset immagine:
Formati file
PNG, JPG, GIF statica, WebP
Dimensione massima del file
5120 kB
Consigli aggiuntivi
- Area di sicurezza dell'immagine: inserisci i contenuti importanti al centro dell'immagine in modo da occuparne l'80%.
Esempio
Kotlin
var movie = MovieEntity.Builder() .setName("Avengers") .addPosterImage(Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(960) .setImageWidthInPixel(408) .build()) .setPlayBackUri(Uri.parse("http://tv.com/playback/1")) .setReleaseDateEpochMillis(1633032895L) .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE) .setDurationMillis(12345678L) .addGenre("action") .addContentRating("R") .setWatchNextType(WatchNextType.TYPE_NEW) .setLastEngagementTimeMillis(1664568895L) .build()
Java
MovieEntity movie = new MovieEntity.Builder() .setName("Avengers") .addPosterImage( new Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(960) .setImageWidthInPixel(408) .build()) .setPlayBackUri(Uri.parse("http://tv.com/playback/1")) .setReleaseDateEpochMillis(1633032895L) .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE) .setDurationMillis(12345678L) .addGenre("action") .addContentRating("R") .setWatchNextType(WatchNextType.TYPE_NEW) .setLastEngagementTimeMillis(1664568895L) .build();
Passaggio 2: fornisci i dati del cluster
È consigliabile eseguire il job di pubblicazione dei contenuti in background (ad esempio, utilizzando WorkManager) e pianificato a intervalli regolari o in base agli eventi (ad esempio, ogni volta che l'utente apre l'app o quando l'utente ha appena aggiunto qualcosa al carrello).
AppEngagePublishClient
è responsabile della pubblicazione dei cluster. Nel client sono disponibili le seguenti API:
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishContinuationCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteContinuationCluster
deleteUserManagementCluster
deleteClusters
isServiceAvailable
Questa API viene utilizzata per verificare se il servizio è disponibile per l'integrazione e se i contenuti possono essere presentati sul dispositivo.
Kotlin
client.isServiceAvailable.addOnCompleteListener { task -> if (task.isSuccessful) { // Handle IPC call success if(task.result) { // Service is available on the device, proceed with content publish // calls. } else { // Service is not available, no further action is needed. } } else { // The IPC call itself fails, proceed with error handling logic here, // such as retry. } }
Java
client.isServiceAvailable().addOnCompleteListener(task - > { if (task.isSuccessful()) { // Handle success if(task.getResult()) { // Service is available on the device, proceed with content publish // calls. } else { // Service is not available, no further action is needed. } } else { // The IPC call itself fails, proceed with error handling logic here, // such as retry. } });
publishRecommendationClusters
Questa API viene utilizzata per pubblicare un elenco di RecommendationCluster
oggetti.
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, le seguenti azioni vengono eseguite nell'ambito di una transazione:
- I dati di
RecommendationCluster
esistenti dal partner sviluppatore verranno rimossi. - I dati della richiesta vengono analizzati e archiviati nel cluster per suggerimenti aggiornato.
In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto lo stato esistente.
publishFeaturedCluster
Questa API viene utilizzata per pubblicare un elenco di FeaturedCluster
oggetti.
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, le seguenti azioni vengono eseguite nell'ambito di una transazione:
- I dati di
FeaturedCluster
esistenti dal partner sviluppatore verranno rimossi. - I dati della richiesta vengono analizzati e archiviati nel cluster in primo piano aggiornato.
In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto lo stato esistente.
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, le seguenti azioni vengono eseguite nell'ambito di una transazione:
- I dati di
ContinuationCluster
esistenti dal partner sviluppatore verranno rimossi. - I dati della richiesta vengono analizzati e archiviati nel cluster di continuazione aggiornato.
In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto lo stato esistente.
publishUserAccountManagementRequest
Questa API viene utilizzata per pubblicare una scheda di accesso . L'azione di accesso indirizza gli utenti alla pagina di accesso dell'app affinché quest'ultima possa pubblicare contenuti (o fornire contenuti più personalizzati)
I seguenti metadati fanno parte della scheda di accesso:
Attributo | Requisito | Descrizione |
---|---|---|
URI azione | Obbligatorio | Link diretto all'azione (ad esempio, consente di accedere alla pagina di accesso dell'app) |
Immagine | Facoltativo: se non viene specificato, è necessario specificare il titolo |
Immagine mostrata nella scheda Immagini con proporzioni 16:9 con una risoluzione di 1264x712 |
Titolo | Facoltativo - Se non viene fornita, è necessario fornire l'immagine | Titolo sulla scheda |
Testo dell'azione | Facoltativo | Testo visualizzato nell'invito all'azione (ad es. Accedi) |
Sottotitolo | Facoltativo | Sottotitolo facoltativo sulla scheda |
Kotlin
var SIGN_IN_CARD_ENTITY = SignInCardEntity.Builder() .addPosterImage( Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build() client.publishUserAccountManagementRequest( PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
Java
SignInCardEntity SIGN_IN_CARD_ENTITY = new SignInCardEntity.Builder() .addPosterImage( new Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build(); client.publishUserAccountManagementRequest( new PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
Quando il servizio riceve la richiesta, le seguenti azioni vengono eseguite nell'ambito di una transazione:
- I dati
UserAccountManagementCluster
esistenti del partner sviluppatore verranno rimossi. - I dati della richiesta vengono analizzati e archiviati nel cluster UserAccountManagementCluster aggiornato.
In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto lo stato esistente.
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 vengono pubblicati (STATUS == PUBBLICATO), è fondamentale per completare le dashboard che utilizzano questo stato esplicito per comunicare lo stato e altre metriche dell'integrazione.
- Se non vengono pubblicati contenuti, ma lo stato dell'integrazione non funziona (STATUS == NOT_PUBED), Google può evitare di attivare avvisi nelle dashboard di integrità dell'app. Conferma che i contenuti non sono stati pubblicati a causa di una situazione prevista dal punto di vista del fornitore.
- Aiuta gli sviluppatori a fornire insight sul momento in cui i dati vengono pubblicati o meno.
- Google potrebbe utilizzare i codici di stato per sollecitare l'utente a eseguire determinate azioni nell'app, in modo da visualizzarne i contenuti o superarli.
Di seguito sono elencati i codici di stato di pubblicazione idonei :
// Content is published
AppEngagePublishStatusCode.PUBLISHED,
// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,
// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,
// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,
// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,
// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,
// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,
// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,
// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER
Se i contenuti non vengono pubblicati perché un utente non ha eseguito l'accesso, Google consiglia di pubblicare la scheda di accesso. Se per qualsiasi motivo i provider non sono in grado di pubblicare la scheda di accesso, ti consigliamo di chiamare l'API updatepublishStatus con il codice di stato NOT_PUBBLICAZIONE_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 il contenuto dei cluster di suggerimenti.
Kotlin
client.deleteRecommendationClusters()
Java
client.deleteRecommendationClusters();
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.
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 il contenuto 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 il contenuto 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 eseguire un'azione di follow-up per recuperare e inviare nuovamente un'attività riuscita.
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster(..) .build()) .addOnCompleteListener { task -> if (task.isSuccessful) { // do something } else { val exception = task.exception if (exception is AppEngageException) { @AppEngageErrorCode val errorCode = exception.errorCode if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) { // do something } } } }
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster(...) .build()) .addOnCompleteListener( task -> { if (task.isSuccessful()) { // do something } else { Exception exception = task.getException(); if (exception instanceof AppEngageException) { @AppEngageErrorCode int errorCode = ((AppEngageException) exception).getErrorCode(); if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) { // do something } } } });
L'errore viene restituito come AppEngageException
con la causa inclusa come
codice di errore.
Codice di errore | Nota |
---|---|
SERVICE_NOT_FOUND |
Il servizio non è disponibile sul dispositivo specificato. |
SERVICE_NOT_AVAILABLE |
Il servizio è disponibile sul dispositivo in questione, ma non al momento della chiamata (ad esempio, è disabilitato esplicitamente). |
SERVICE_CALL_EXECUTION_FAILURE |
Esecuzione dell'attività non riuscita a causa di problemi di organizzazione in thread. In questo caso, sarà possibile riprovare. |
SERVICE_CALL_PERMISSION_DENIED |
Il chiamante non è autorizzato a effettuare la chiamata di servizio. |
SERVICE_CALL_INVALID_ARGUMENT |
La richiesta contiene dati non validi (ad esempio, più del numero consentito di cluster). |
SERVICE_CALL_INTERNAL |
È presente un errore sul lato servizio. |
SERVICE_CALL_RESOURCE_EXHAUSTED |
La chiamata al servizio viene effettuata troppo spesso. |
Passaggio 3: gestisci gli intent di trasmissione
Oltre a effettuare chiamate alla Content API per la pubblicazione 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 forzatura della sincronizzazione dei dati. Gli intent di trasmissione non sono progettati per essere inviati molto di frequente. Viene attivato solo quando il servizio Engage determina che i contenuti potrebbero essere obsoleti (ad esempio, una settimana fa). In questo modo, si può avere più sicurezza che l'utente possa avere un'esperienza con i contenuti aggiornati, anche se l'applicazione non è stata eseguita per un lungo periodo di tempo.
BroadcastReceiver
deve essere configurato nei due modi seguenti:
- Registra dinamicamente un'istanza della classe
BroadcastReceiver
utilizzandoContext.registerReceiver()
. Ciò consente la comunicazione dalle applicazioni ancora presenti 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>
nel fileAndroidManifest.xml
. Ciò consente all'applicazione di ricevere intent di trasmissione quando non è in esecuzione e all'applicazione di pubblicare i contenuti.
<application>
<receiver
android:name=".AppEngageBroadcastReceiver"
android:exported="true"
android:enabled="true">
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
</intent-filter>
</receiver>
</application>
Il servizio invia i seguenti intent:
com.google.android.engage.action.PUBLISH_RECOMMENDATION
Ti consigliamo di avviare una chiamatapublishRecommendationClusters
quando ricevi questo intent.com.google.android.engage.action.PUBLISH_FEATURED
È consigliabile avviare una chiamatapublishFeaturedCluster
quando ricevi questo intent.com.google.android.engage.action.PUBLISH_CONTINUATION
Ti consigliamo di avviare una chiamatapublishContinuationCluster
quando ricevi questo intent.
Flusso di lavoro di integrazione
Per una guida passo passo sulla verifica dell'integrazione dopo il completamento, consulta Flusso di lavoro dell'integrazione per gli sviluppatori sul coinvolgimento.
Domande frequenti
Consulta le Domande frequenti sull'SDK Engage per le domande frequenti.
Contact
Contatta engagement-developers@google.com in caso di domande durante la procedura di integrazione.
Passaggi successivi
Una volta completata l'integrazione, i passaggi successivi sono i seguenti:
- Invia un'email all'indirizzo Engage-developers@google.com e allega l'APK integrato pronto per i test di Google.
- Google esegue una verifica ed esamina internamente per assicurarsi che l'integrazione funzioni come previsto. Se sono necessarie modifiche, Google ti contatta fornendoti tutti i dettagli necessari.
- Quando il test è completo e non sono necessarie modifiche, Google ti contatta per informarti che puoi iniziare a pubblicare l'APK aggiornato e integrato nel Play Store.
- Dopo che Google avrà confermato che l'APK aggiornato è stato pubblicato sul Play Store, i cluster Consigli, In primo piano e Continuazione potrebbero essere pubblicati e visibili agli utenti.