Aumenta il coinvolgimento nell'app raggiungendo gli utenti ovunque si trovino. Integra l'SDK Engage per fornire consigli personalizzati e contenuti di continuazione direttamente agli utenti su più piattaforme on-device, come Raccolte, Spazio Intrattenimento e il Play Store. L'integrazione aggiunge meno di 50 KB (compressi) all'APK medio e richiede agli sviluppatori circa una settimana di tempo per la maggior parte delle app. Scopri di più sul nostro sito aziendale.
Questa guida contiene le istruzioni per i partner sviluppatori per la pubblicazione di contenuti audio (musica, podcast, audiolibri, radio in diretta) sulle piattaforme di contenuti di Engage.
Dettaglio integrazione
Terminologia
Questa integrazione include i seguenti tre tipi di cluster: Consigliati, Continua a guardare e In primo piano.
I cluster di consigli mostrano suggerimenti personalizzati sui contenuti da leggere di un singolo partner sviluppatore.
I consigli hanno la seguente struttura:
Cluster di suggerimenti:una visualizzazione dell'interfaccia utente che contiene un gruppo di suggerimenti 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 una playlist, un audiolibro, un podcast e altro ancora. Consulta la sezione Fornire 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 contenuti audio con cui gli utenti hanno interagito di recente di più partner sviluppatori in un unico raggruppamento dell'interfaccia utente. A ogni partner di sviluppo sarà consentito trasmettere un massimo di 10 entità nel cluster Continuità.
Figura 3. Interfaccia utente di Entertainment Space che mostra un cluster di continuazione con consigli non completati di più partner (attualmente è visibile un solo consiglio). Il cluster In evidenza mostra una selezione di elementi di più partner sviluppatori in un unico raggruppamento dell'interfaccia utente. Verrà visualizzato un singolo cluster In primo piano nella parte superiore della UI, con un posizionamento prioritario rispetto a tutti gli altri cluster di consigli. A ogni partner sviluppatore sarà consentito di 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 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.5.2'
}
Riepilogo
Il design si basa sull'implementazione di un servizio associato.
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 delle entità in un cluster |
---|---|---|
Cluster di consigli | Al massimo 7 | Al massimo 50 |
Continuation Cluster | Al massimo 1 | Al massimo 20 |
Cluster in primo piano | Al massimo 1 | Al massimo 20 |
Passaggio 1: fornisci i dati dell'entità
L'SDK ha definito entità diverse per rappresentare ogni tipo di elemento. Supportiamo le seguenti entità per la categoria Ascolta:
MusicAlbumEntity
MusicArtistEntity
MusicTrackEntity
MusicVideoEntity
PlaylistEntity
PodcastSeriesEntity
PodcastEpisodeEntity
LiveRadioStationEntity
AudiobookEntity
I grafici riportati di seguito illustrano gli attributi e i requisiti disponibili per ogni tipo.
MusicAlbumEntity
L'oggetto MusicAlbumEntity
rappresenta un album musicale (ad esempio, Midnights
di Taylor Swift).
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | Il titolo dell'album musicale. |
Immagini poster | Obbligatorio | Devi fornire almeno un'immagine. Consulta Specifiche per le immagini per indicazioni. |
URI della pagina di informazioni | Obbligatorio |
Il link diretto all'app del fornitore per i dettagli sull'album musicale. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Artisti | Obbligatorio | Elenco degli artisti nell'album musicale. |
URI di riproduzione | Facoltativo |
Un link diretto che avvia la riproduzione dell'album nell'app del fornitore. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Descrizione | Facoltativo | Se fornito, non deve superare i 200 caratteri. |
Conteggio brani | Facoltativo | Il numero di brani nell'album musicale. |
Generi | Facoltativo | Elenco dei generi dell'album musicale. |
Formato album | Facoltativo |
ALBUM (include LP e doppio LP) EP SINGOLA Mixtape |
Case discografiche | Facoltativo | Elenco delle case discografiche associate all'album. |
Scaricato sul dispositivo | Facoltativo | Valore booleano che indica se l'album musicale è stato scaricato sul dispositivo. |
Esplicito | Facoltativo |
Un valore booleano che indica se i contenuti sono espliciti o meno Gli elementi che contengono materiale esplicito o che presentano un avviso per i genitori devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con il tag "E". |
Data di uscita | Facoltativo | La data di uscita dell'album in millisecondi dell'epoca. |
Durata | Facoltativo | La durata dell'album in millisecondi. |
Ora ultimo coinvolgimento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi epoch |
Percentuale di avanzamento del completamento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Numero intero compreso tra 0 e 100 |
MusicArtistEntity
L'oggetto MusicArtistEntity
rappresenta un artista musicale (ad esempio, Adele).
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | Il nome dell'artista musicale. |
Immagini poster | Obbligatorio | Devi fornire almeno un'immagine. Consulta Specifiche per le immagini per indicazioni. |
URI della pagina di informazioni | Obbligatorio |
Il link diretto all'app del fornitore per i dettagli sull'artista musicale. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
URI di riproduzione | Facoltativo |
Il link diretto che avvia la riproduzione dei brani dell'artista nell'app del fornitore. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Descrizione | Facoltativo | Se fornito, non deve superare i 200 caratteri. |
Ora ultimo coinvolgimento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi epoch |
MusicTrackEntity
L'oggetto MusicTrackEntity
rappresenta una traccia musicale (ad esempio Yellow di
Coldplay).
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | Il titolo della traccia musicale. |
Immagini poster | Obbligatorio | Devi fornire almeno un'immagine. Consulta Specifiche per le immagini per indicazioni. |
URI di riproduzione | Obbligatorio |
Un link diretto che avvia la riproduzione della traccia musicale nell'app del fornitore. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Artisti | Obbligatorio | Elenco degli artisti per la traccia musicale. |
URI della pagina di informazioni | Facoltativo |
Un link diretto all'app del fornitore per i dettagli sul brano musicale. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Descrizione | Facoltativo | Se fornito, non deve superare i 200 caratteri. |
Durata | Facoltativo | La durata della traccia in millisecondi. |
Album | Facoltativo | Il nome dell'album a cui appartiene il brano. |
Scaricato sul dispositivo | Facoltativo | Valore booleano che indica se la traccia musicale è stata scaricata sul dispositivo. |
Esplicito | Facoltativo |
Un valore booleano che indica se i contenuti sono espliciti o meno Gli elementi che contengono materiale esplicito o che presentano un avviso per i genitori devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con il tag "E". |
Ora ultimo coinvolgimento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi epoch |
Percentuale di avanzamento del completamento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Numero intero compreso tra 0 e 100 |
MusicVideoEntity
L'oggetto MusicVideoEntity
rappresenta un video musicale (ad esempio,
The Weeknd - Take My Breath (Official Music Video)).
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | Il titolo del video musicale. |
Immagini poster | Obbligatorio | Devi fornire almeno un'immagine. Consulta Specifiche per le immagini per indicazioni. |
URI di riproduzione | Obbligatorio |
Un link diretto che avvia la riproduzione del video musicale nell'app del fornitore. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
URI della pagina di informazioni | Facoltativo |
Un link diretto all'app del fornitore per i dettagli sul video musicale. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Durata | Facoltativo | La durata del video espressa in millisecondi. |
Numero di visualizzazioni | Facoltativo | Il numero di visualizzazioni del video in formato di testo libero. |
Artisti | Facoltativo | Elenco degli artisti del video musicale. |
Classificazione dei contenuti | Facoltativo | Elenco delle classificazioni dei contenuti della traccia. |
Descrizione | Facoltativo | Se fornito, non deve superare i 200 caratteri. |
Scaricato sul dispositivo | Facoltativo | Valore booleano che indica se il video musicale è stato scaricato sul dispositivo. |
Esplicito | Facoltativo |
Un valore booleano che indica se i contenuti sono espliciti o meno Gli elementi che contengono materiale esplicito o che presentano un avviso per i genitori devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con il tag "E". |
Ora ultimo coinvolgimento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi epoch |
Percentuale di avanzamento del completamento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Numero intero compreso tra 0 e 100 |
PlaylistEntity
L'oggetto PlaylistEntity
rappresenta una playlist musicale (ad esempio, la playlist Top 10 degli Stati Uniti).
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | Il titolo della playlist. |
Immagini poster | Obbligatorio | Devi fornire almeno un'immagine. Consulta Specifiche per le immagini per indicazioni. |
URI di riproduzione | Obbligatorio |
Un link diretto che avvia la riproduzione della playlist musicale nell'app del fornitore. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
URI della pagina di informazioni | Facoltativo |
Un link diretto all'app del fornitore per i dettagli sulla playlist musicale. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Durata | Facoltativo | La durata della playlist in millisecondi. |
Conteggio brani | Facoltativo | Il numero di brani nella playlist musicale. |
Descrizione | Facoltativo | Se fornito, non deve superare i 200 caratteri. |
Scaricato sul dispositivo | Facoltativo | Valore booleano che indica se la playlist è stata scaricata sul dispositivo. |
Esplicito | Facoltativo |
Un valore booleano che indica se i contenuti sono espliciti o meno Gli elementi che contengono materiale esplicito o che presentano un avviso per i genitori devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con il tag "E". |
Ora ultimo coinvolgimento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi epoch |
Percentuale di avanzamento del completamento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Numero intero compreso tra 0 e 100 |
PodcastSeriesEntity
L'oggetto PodcastSeriesEntity
rappresenta una serie di podcast (ad esempio, This
American Life).
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | Titolo della serie podcast. |
Immagini poster | Obbligatorio | Devi fornire almeno un'immagine. Consulta Specifiche per le immagini per indicazioni. |
URI della pagina di informazioni | Obbligatorio |
Un link diretto all'app del fornitore per i dettagli sulla serie di podcast. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
URI di riproduzione | Facoltativo |
Un link diretto che avvia la riproduzione della serie di podcast nell'app del fornitore. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Conteggio puntate | Facoltativo | Il numero di episodi della serie di podcast. |
Nome della produzione | Facoltativo | Il nome della produzione della serie di podcast. |
Host | Facoltativo | Elenco dei conduttori della serie podcast. |
Generi | Facoltativo | Elenco dei generi della serie podcast. |
Scaricato sul dispositivo | Facoltativo | Valore booleano che indica se il podcast è stato scaricato sul dispositivo. |
Descrizione | Facoltativo | Se fornito, non deve superare i 200 caratteri. |
Esplicito | Facoltativo |
Un valore booleano che indica se i contenuti sono espliciti o meno Gli elementi che contengono materiale esplicito o che presentano un avviso per i genitori devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con il tag "E". |
Ora ultimo coinvolgimento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi epoch |
PodcastEpisodeEntity
L'oggetto PodcastEpisodeEntity
rappresenta una serie di podcast (ad esempio,
Spark Bird, Episode 754: This American Life).
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | Titolo della puntata del podcast. |
Immagini poster | Obbligatorio | Devi fornire almeno un'immagine. Consulta Specifiche per le immagini per indicazioni. |
URI di riproduzione | Obbligatorio |
Un link diretto che avvia la riproduzione della puntata del podcast nell'app del fornitore. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Titolo della serie podcast | Obbligatorio | Il nome della serie di podcast a cui appartiene l'episodio. |
Durata | Obbligatorio | La durata della puntata del podcast in millisecondi. |
Data di pubblicazione | Obbligatorio | Data di pubblicazione del podcast (in millisecondi epoch) |
URI della pagina di informazioni | Facoltativo |
Un link diretto all'app del fornitore per i dettagli sulla puntata del podcast. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Nome della produzione | Facoltativo | Il nome della produzione della serie di podcast. |
Indice delle puntate | Facoltativo | L'indice dell'episodio nella serie (il primo indice è 1). |
Host | Facoltativo | Elenco dei conduttori della puntata del podcast. |
Generi | Facoltativo | Elenco dei generi della puntata del podcast. |
Scaricato sul dispositivo | Facoltativo | Valore booleano che indica se la puntata del podcast è stata scaricata sul dispositivo. |
Descrizione | Facoltativo | Se fornito, non deve superare i 200 caratteri. |
Podcast video | Facoltativo | Valore booleano che indica se la puntata del podcast contiene contenuti video |
Esplicito | Facoltativo |
Un valore booleano che indica se i contenuti sono espliciti o meno Gli elementi che contengono materiale esplicito o che presentano un avviso per i genitori devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con il tag "E". |
Tipo di ascolto successivo | Facoltativo |
Consigliato per gli elementi nel cluster di continuazione TYPE_CONTINUE: riprendi la riproduzione di un elemento audio non completato. TYPE_NEXT - Continua con un nuovo episodio di una serie. TYPE_NEW: appena rilasciato. |
Ora ultimo coinvolgimento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi epoch |
Percentuale di avanzamento del completamento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Numero intero compreso tra 0 e 100 |
LiveRadioStationEntity
L'oggetto LiveRadioStationEntity
rappresenta una stazione radio live (ad esempio, 98.1 The Breeze).
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | Titolo della stazione radio in diretta. |
Immagini poster | Obbligatorio | Devi fornire almeno un'immagine. Consulta Specifiche per le immagini per indicazioni. |
URI di riproduzione | Obbligatorio |
Un link diretto che avvia la riproduzione della stazione radio nell'app del fornitore. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
URI della pagina di informazioni | Facoltativo |
Un link diretto all'app del fornitore per i dettagli sulla stazione radio. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Frequenza | Facoltativo | La frequenza di trasmissione della stazione radio (ad esempio, "98.1 FM"). |
Mostra titolo | Facoltativo | Il programma attualmente in riproduzione sulla stazione radio. |
Host | Facoltativo | Elenco dei conduttori della stazione radio. |
Descrizione | Facoltativo | Se fornito, non deve superare i 200 caratteri. |
Ora ultimo coinvolgimento | Facoltativo |
Consigliato per gli articoli nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi epoch |
AudiobookEntity
L'oggetto AudiobookEntity
rappresenta un audiolibro (ad esempio, l'audiolibro
di Becoming di Michelle Obama).
Attributo | Requisito | Note |
---|---|---|
Nome | Obbligatorio | |
Immagini poster | Obbligatorio | Devi fornire almeno un'immagine. Consulta le specifiche delle immagini per indicazioni. |
Autore | Obbligatorio | Specifica almeno un nome dell'autore. |
URI del link all'azione | Obbligatorio |
Il link diretto all'app del fornitore per l'audiobook. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti |
Narratore | Facoltativo | Specifica almeno un nome del narratore. |
Data di pubblicazione | Facoltativo | In millisecondi dell'epoca di Unix, se fornito. |
Descrizione | Facoltativo | Se fornito, non deve superare i 200 caratteri. |
Prezzo | Facoltativo | Testo libero |
Durata | Facoltativo | Se specificato, deve essere un valore positivo. |
Genere | Facoltativo | Elenco dei generi associati al libro. |
Nome serie | Facoltativo | Il nome della serie a cui appartiene l'audiolibro (ad esempio, Harry Potter). |
Indice unità serie | Facoltativo | L'indice dell'audiolibro nella serie, dove 1 è il primo audiolibro della serie. Ad esempio, se Harry Potter e il prigioniero di Azkaban è il terzo libro della serie, questo valore deve essere impostato su 3. |
Tipo di libro continua | Facoltativo |
TYPE_CONTINUE: riprendi la lettura di un libro non terminato. TYPE_NEXT - Continua con un nuovo episodio di una serie. TYPE_NEW: appena rilasciato. |
Data/ora ultimo coinvolgimento | Obbligatorio condizionalmente | Deve essere fornito quando l'articolo si trova nel cluster Continuazione. In millisecondi dall'epoca. |
Percentuale di avanzamento completata | Obbligatorio condizionalmente |
Deve essere fornito quando l'articolo si trova nel cluster Continuazione. Gli audiolibri acquisiti *di recente* possono far parte del cluster Continua a leggere. Il valore deve essere maggiore di 0 e inferiore a 100. |
DisplayTimeWindow: imposta un intervallo di tempo per la visualizzazione di un contenuto sulla piattaforma | ||
Timestamp di inizio | Facoltativo |
Il timestamp epoch dopo il quale i contenuti devono essere mostrati sulla piattaforma. Se non è impostato, i contenuti sono idonei a essere visualizzati sulla piattaforma. In millisecondi dall'epoca. |
Timestamp fine | Facoltativo |
Il timestamp dell'epoca dopo il quale i contenuti non vengono più visualizzati sulla piattaforma. Se non è impostato, i contenuti sono idonei a essere visualizzati sulla piattaforma. In millisecondi dall'epoca. |
Specifiche per le immagini
Di seguito sono elencate le specifiche obbligatorie per gli asset immagine:
Proporzioni | Requisito | Numero minimo di pixel | Numero consigliato di pixel |
---|---|---|---|
Quadrato (1 x 1) | Obbligatorio | 300x300 | 1200x1200 |
Orizzontale (1,91 x 1) | Facoltativo | 600x314 | 1200x628 |
Verticale (4x5) | Facoltativo | 480x600 | 960x1200 |
Formati file
PNG, JPG, GIF statico, WebP
Dimensioni massime del file
5120 kB
Altri consigli
- Area di sicurezza dell'immagine:inserisci i contenuti importanti al centro dell'immagine in modo da occuparne l'80%.
Esempi
MusicAlbumEntity musicAlbumEntity =
new MusicAlbumEntity.Builder()
.setName(NAME)
.addPosterImage(new Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(960)
.setImageWidthInPixel(408)
.build())
.setPlayBackUri("https://play.google/album/play")
.setInfoPageUri("https://play.google/album/info")
.setDescription("A description of this album.")
.addArtist("Artist")
.addGenre("Genre")
.addMusicLabel("Label")
.addContentRating("Rating")
.setSongsCount(960)
.setReleaseDateEpochMillis(1633032895L)
.setDurationMillis(1633L)
.build();
AudiobookEntity audiobookEntity =
new AudiobookEntity.Builder()
.setName("Becoming")
.addPosterImage(new Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(960)
.setImageWidthInPixel(408)
.build())
.addAuthor("Michelle Obama")
.addNarrator("Michelle Obama")
.setActionLinkUri(
Uri.parse("https://play.google/audiobooks/1"))
.setDurationMillis(16335L)
.setPublishDateEpochMillis(1633032895L)
.setDescription("An intimate, powerful, and inspiring memoir")
.setPrice("$16.95")
.addGenre("biography")
.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 qualcosa al carrello).
AppEngagePublishClient
è responsabile della pubblicazione dei cluster. Le seguenti
API sono disponibili nel client:
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("Trending music")
.build())
.build())
Java
client.publishRecommendationClusters(
new PublishRecommendationClustersRequest.Builder()
.addRecommendationCluster(
new RecommendationCluster.Builder()
.addEntity(entity1)
.addEntity(entity2)
.setTitle("Trending music")
.build())
.build());
Quando il servizio riceve la richiesta, vengono eseguite le seguenti azioni in 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()
...
.build())
.build())
Java
client.publishFeaturedCluster(
new PublishFeaturedClusterRequest.Builder()
.setFeaturedCluster(
new FeaturedCluster.Builder()
...
.build())
.build());
Quando il servizio riceve la richiesta, vengono eseguite le seguenti azioni in 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(
PublishContinuationClusterRequest.Builder()
.setContinuationCluster(
ContinuationCluster.Builder()
.addEntity(entity1)
.addEntity(entity2)
.build())
.build())
Quando il servizio riceve la richiesta, vengono eseguite le seguenti azioni in 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 di accesso:
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:9 e risoluzione 1264 x 712 |
Titolo | Facoltativo: se non fornito, l'immagine è obbligatoria | Titolo sulla carta |
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, vengono eseguite le seguenti azioni in 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 nessuno dei cluster viene pubblicato, 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 == 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 nei dashboard sull'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 di accesso. Se per qualsiasi motivo i fornitori non sono in grado di pubblicare la scheda di accesso, ti consigliamo di chiamare l'API updatePublishStatus con il codice di stato NOT_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 cluster 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_FEATURED)
.addClusterType(ClusterType.TYPE_RECOMMENDATION)
...
.build())
Java
client.deleteClusters(
new DeleteClustersRequest.Builder()
.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 clienti possono scegliere di trasmettere uno o più tipi di cluster. In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.
Gestione degli errori
È consigliabile 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.
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, può essere riprovato. |
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 spesso. |
Passaggio 3: gestisci gli intent di trasmissione
Oltre a effettuare chiamate API per la pubblicazione di contenuti tramite un job, è anche
necessario configurare un
BroadcastReceiver
per ricevere
la richiesta di pubblicazione di contenuti.
Lo scopo 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 spesso. Viene attivato solo quando il servizio Engage determina che i contenuti potrebbero essere obsoleti (ad esempio, una settimana). In questo modo, l'utente può avere maggiore fiducia di poter usufruire di un'esperienza con contenuti nuovi, 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 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),
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 fileAndroidManifest.xml
. Ciò consente all'applicazione di ricevere intent di trasmissione quando non è in esecuzione e di pubblicare i contenuti.
<application>
<receiver
android:name=".AppEngageBroadcastReceiver"
android: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>
I seguenti intent verranno inviati dal servizio:
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.
Workflow di integrazione
Per una guida passo passo alla verifica dell'integrazione una volta completata, consulta Flusso di lavoro di integrazione per sviluppatori di Engage.
Domande frequenti
Consulta le Domande frequenti sull'SDK Engage.
Contatto
Contatta
engage-developers@google.com
in caso di
domande durante la procedura di integrazione. Il nostro team ti risponderà il prima
possibile.
Passaggi successivi
Dopo aver completato questa integrazione, i passaggi successivi sono i seguenti:
- Invia un'email a
engage-developers@google.com
e allega l'APK integrato pronto per il test da parte di Google. - Google eseguirà una verifica e un controllo interni per assicurarsi che l'integrazione funzioni come previsto. Se sono necessarie modifiche, Google ti contatterà con i dettagli necessari.
- Al termine del test e se non sono necessarie modifiche, Google ti contatterà per comunicarti che puoi iniziare a pubblicare l'APK aggiornato e integrato sul Play Store.
- Dopo che Google avrà confermato la pubblicazione dell'APK aggiornato sul Play Store, i cluster Consigliati, In primo piano e Continua verranno pubblicati e saranno visibili agli utenti.