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

Aumenta il coinvolgimento con l'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 di intrattenimento 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 uno sviluppatore. Scopri di più sul nostro sito dell'attività.

Questa guida contiene le istruzioni per gli sviluppatori partner per pubblicare contenuti audio (musica, podcast, audiolibri, radio in diretta) sulle piattaforme di contenuti Engage.

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 per i contenuti da leggere 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 una playlist, un audiolibro, un podcast e altro ancora. Consulta la sezione Fornire dati sulle 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 di cui gli utenti si sono recentemente interessati da più sviluppatori partner in un unico raggruppamento dell'interfaccia utente. Ogni sviluppatore partner potrà trasmettere un massimo di 10 entità nel cluster di continuazione.

    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 evidenza mostra una selezione di elementi di più sviluppatori partner in un unico raggruppamento dell'interfaccia utente. Verrà visualizzato un singolo cluster in primo piano, che verrà 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'
}

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 Massimo 50
Cluster di continuazione Al massimo 1 Al massimo 20
Cluster in primo piano Al massimo 1 Al massimo 20

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 Ascolta:

  1. MusicAlbumEntity
  2. MusicArtistEntity
  3. MusicTrackEntity
  4. MusicVideoEntity
  5. PlaylistEntity
  6. PodcastSeriesEntity
  7. PodcastEpisodeEntity
  8. LiveRadioStationEntity
  9. AudiobookEntity

I grafici riportati di seguito illustrano gli attributi e i requisiti disponibili per ciascun tipo.

MusicAlbumEntity

L'oggetto MusicAlbumEntity rappresenta un album musicale (ad es. Midnights di Taylor Swift).

Attributo Requisito Note
Nome Obbligatorio Il titolo dell'album musicale.
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta Specifiche per le immagini.
URI pagina informativa Obbligatorio

Il link diretto all'app del fornitore per i dettagli sull'album musicale.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente

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 questa domanda frequente

Descrizione Facoltativo Se specificato, deve avere una lunghezza massima di 200 caratteri.
Conteggio brani Facoltativo Il numero di brani nell'album musicale.
Generi Facoltativo Elenco dei generi nell'album musicale.
Formato album Facoltativo

ALBUM (inclusi 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 un tag "E".

Data di uscita Facoltativo La data di uscita dell'album in millisecondi epoch.
Durata Facoltativo La durata dell'album in millisecondi.
Ora dell'ultimo coinvolgimento Facoltativo

Consigliato per gli elementi del cluster di continuazione. Può essere utilizzato per il ranking.

In millisecondi epoch

Percentuale di avanzamento completata Facoltativo

Consigliato per gli elementi del 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 Nome dell'artista musicale.
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta Specifiche per le immagini.
URI pagina informativa Obbligatorio

Il link diretto all'app del fornitore per i dettagli sull'artista.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente

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 questa domanda frequente

Descrizione Facoltativo Se specificato, deve avere una lunghezza massima di 200 caratteri.
Ora dell'ultimo coinvolgimento Facoltativo

Consigliato per gli elementi del cluster di continuazione. Può essere utilizzato per il ranking.

In millisecondi epoch

MusicTrackEntity

L'oggetto MusicTrackEntity rappresenta una traccia audio (ad es. Yellow dei Coldplay).

Attributo Requisito Note
Nome Obbligatorio Titolo della traccia audio.
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta Specifiche per le immagini.
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 questa domanda frequente

Artisti Obbligatorio Elenco degli artisti del brano musicale.
URI pagina informativa Facoltativo

Un link diretto all'app del fornitore per i dettagli sulla traccia audio.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente

Descrizione Facoltativo Se specificato, deve avere una lunghezza massima di 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 un tag "E".

Ora dell'ultimo coinvolgimento Facoltativo

Consigliato per gli elementi del cluster di continuazione. Può essere utilizzato per il ranking.

In millisecondi epoch

Percentuale di avanzamento completata Facoltativo

Consigliato per gli elementi del cluster di continuazione.

Numero intero compreso tra 0 e 100

MusicVideoEntity

L'oggetto MusicVideoEntity rappresenta un video musicale (ad es. The Weeknd - Take My Breath (Official Music Video)).

Attributo Requisito Note
Nome Obbligatorio Titolo del video musicale.
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta Specifiche per le immagini.
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 questa domanda frequente

URI pagina informativa Facoltativo

Un link diretto all'app del fornitore per i dettagli del video musicale.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente

Durata Facoltativo La durata del video 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 del canale.
Descrizione Facoltativo Se specificato, deve avere una lunghezza massima di 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 un tag "E".

Ora dell'ultimo coinvolgimento Facoltativo

Consigliato per gli elementi del cluster di continuazione. Può essere utilizzato per il ranking.

In millisecondi epoch

Percentuale di avanzamento completata Facoltativo

Consigliato per gli elementi del 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 Titolo della playlist.
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta Specifiche per le immagini.
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 questa domanda frequente

URI pagina informativa Facoltativo

Un link diretto all'app del fornitore per i dettagli sulla playlist musicale.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente

Durata Facoltativo La durata della playlist in millisecondi.
Conteggio brani Facoltativo Il numero di brani nella playlist musicale.
Descrizione Facoltativo Se specificato, deve avere una lunghezza massima di 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 un tag "E".

Ora dell'ultimo coinvolgimento Facoltativo

Consigliato per gli elementi del cluster di continuazione. Può essere utilizzato per il ranking.

In millisecondi epoch

Percentuale di avanzamento completata Facoltativo

Consigliato per gli elementi del 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 di podcast.
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta Specifiche per le immagini.
URI pagina informativa 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 questa domanda frequente

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 questa domanda frequente

Numero di puntate Facoltativo Il numero di puntate della serie di podcast.
Nome della produzione Facoltativo Il nome della produzione della serie di podcast.
Host Facoltativo Elenco dei conduttori della serie di podcast.
Generi Facoltativo Elenco dei generi della serie di podcast.
Scaricati sul dispositivo Facoltativo Valore booleano che indica se il podcast è stato scaricato sul dispositivo.
Descrizione Facoltativo Se specificato, deve avere una lunghezza massima di 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 un tag "E".

Ora dell'ultimo coinvolgimento Facoltativo

Consigliato per gli elementi del 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, puntata 754: This American Life).

Attributo Requisito Note
Nome Obbligatorio Titolo della puntata del podcast.
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta Specifiche per le immagini.
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 questa domanda frequente

Titolo della serie di podcast Obbligatorio Il nome della serie di podcast a cui appartiene la puntata.
Durata Obbligatorio La durata della puntata del podcast in millisecondi.
Data di pubblicazione Obbligatorio Data di pubblicazione del podcast (in millisecondi epoch)
URI pagina informativa 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 questa domanda frequente

Nome della produzione Facoltativo Il nome della produzione della serie di podcast.
Indice delle puntate Facoltativo L'indice della puntata nella serie (il primo indice è 1).
Host Facoltativo Elenco dei conduttori della puntata del podcast.
Generi Facoltativo Elenco dei generi della puntata del podcast.
Scaricati sul dispositivo Facoltativo Valore booleano che indica se la puntata del podcast è stata scaricata sul dispositivo.
Descrizione Facoltativo Se specificato, deve avere una lunghezza massima di 200 caratteri.
Podcast video Facoltativo Valore booleano che indica se la puntata del podcast include 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 un tag "E".

Tipo di ascolto successivo Facoltativo

Consigliato per gli elementi nel cluster di continuazione

TYPE_CONTINUE: riprendi da un elemento audio non completato.

TYPE_NEXT: passa a un nuovo elemento di una serie.

TYPE_NEW: appena rilasciato.

Ora dell'ultimo coinvolgimento Facoltativo

Consigliato per gli elementi del cluster di continuazione. Può essere utilizzato per il ranking.

In millisecondi epoch

Percentuale di avanzamento completata Facoltativo

Consigliato per gli elementi del cluster di continuazione.

Numero intero compreso tra 0 e 100

LiveRadioStationEntity

L'oggetto LiveRadioStationEntity rappresenta una stazione radio in diretta (ad es. 98.1 The Breeze).

Attributo Requisito Note
Nome Obbligatorio Titolo della stazione radio in diretta.
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta Specifiche per le immagini.
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 questa domanda frequente

URI pagina informativa Facoltativo

Un link diretto all'app del fornitore per i dettagli sulla stazione radio.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente

Frequenza Facoltativo La frequenza su cui viene trasmessa la 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 specificato, deve avere una lunghezza massima di 200 caratteri.
Ora dell'ultimo coinvolgimento Facoltativo

Consigliato per gli elementi del 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 dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta le specifiche per le immagini.
Autore Obbligatorio Devi specificare almeno un nome dell'autore.
URI del link all'azione Obbligatorio

Il link diretto all'app del fornitore per l'audiolibro.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta questa domanda frequente

Narratore Facoltativo Devi specificare almeno un nome di narratore.
Data di pubblicazione Facoltativo In millisecondi epoch, se specificato.
Descrizione Facoltativo Se specificato, deve avere una lunghezza massima di 200 caratteri.
Prezzo Facoltativo Testo libero
Durata Facoltativo Deve essere un valore positivo, se specificato.
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 delle unità di misura della serie Facoltativo L'indice dell'audiolibro nella serie, dove 1 è il primo audiolibro nella 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 successivo Facoltativo

TYPE_CONTINUE: riprendi da un libro non completato.

TYPE_NEXT: passa a un nuovo elemento di una serie.

TYPE_NEW: appena rilasciato.

Ora ultimo coinvolgimento Obbligatorio condizionalmente

Deve essere fornito quando l'elemento si trova nel cluster Continuità.

In millisecondi dall'epoca.

Percentuale di avanzamento completata Obbligatorio condizionalmente

Deve essere fornito quando l'elemento si trova nel cluster Continuità.

Gli audiolibri *appena* acquisiti possono far parte del cluster di lettura continua.

Il valore deve essere maggiore di 0 e inferiore a 100.

DisplayTimeWindow: imposta una finestra temporale per la visualizzazione di contenuti sulla piattaforma
Timestamp inizio Facoltativo

Il timestamp epoch dopo il quale i contenuti devono essere visualizzati sulla piattaforma.

Se non è impostato, i contenuti sono idonei alla visualizzazione sulla piattaforma.

In millisecondi dall'epoca.

Timestamp fine Facoltativo

Il timestamp epoch dopo il quale i contenuti non vengono più visualizzati sulla piattaforma.

Se non è impostato, i contenuti sono idonei alla visualizzazione sulla piattaforma.

In millisecondi dall'epoca.

Specifiche per le immagini

Di seguito sono elencate le specifiche richieste per gli asset immagine:

Proporzioni Requisito Numero minimo di pixel Risoluzione consigliata in pixel
Quadrato (1 x 1) Obbligatorio 300x300 1200x1200
Orizzontale (1,91 x 1) Facoltativo 600x314 1200x628
Ritratto (4 x 5) Facoltativo 480x600 960x1200

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%.

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 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("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 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()
                        ...
                        .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 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(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    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 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 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.

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 in modo dinamico un'istanza della classe BroadcastReceiver utilizzando Context.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),
                           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 in modo statico un'implementazione con il tag <receiver> nel AndroidManifest.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:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

Il servizio invierà i seguenti intent:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION Ti consigliamo di avviare una chiamata publishRecommendationClusters quando ricevi questa intenzione.
  • com.google.android.engage.action.PUBLISH_FEATURED È consigliabile avviare una chiamata publishFeaturedCluster quando si riceve questo intento.
  • com.google.android.engage.action.PUBLISH_CONTINUATION È consigliabile avviare una chiamata publishContinuationCluster 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. Il nostro team risponderà il prima possibile.

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 eseguirà una verifica e una revisione interna 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 contatterà 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 verranno pubblicati e saranno visibili agli utenti.