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

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 audio, utilizzando l'SDK Engage per completare sia questa nuova area di lavoro 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 per i contenuti da leggere 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.

    

    Figura 1. UI di Entertainment Space che mostra un cluster di suggerimenti 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 dell'entità per un elenco dei tipi di entità supportati.

    

    Figura 2. UI di Entertainment Space che mostra una singola entità all'interno di un cluster di suggerimenti di un singolo partner.

• Il cluster Continuazione mostra i contenuti audio coinvolti di recente dagli utenti di più sviluppatori partner in un unico raggruppamento di UI. Ogni partner di sviluppo potrà trasmettere un massimo di 10 entità nel cluster di continuazione.

  

  Figura 3. UI di Entertainment Space che mostra un cluster di continuazione con suggerimenti non completati da più partner (al momento è visibile un solo consiglio).

• Il cluster In primo piano mostra una selezione di elementi di più partner di sviluppatori in un unico raggruppamento di UI. Ci sarà un unico cluster In primo piano, che verrà visualizzato nella parte superiore dell'interfaccia utente con un posizionamento di priorità sopra tutti i cluster di suggerimenti. A ogni sviluppatore partner sarà consentito trasmettere fino a 10 entità nel cluster in primo piano.

  

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

Preparazione

Livello API minimo: 19

Aggiungi la raccolta com.google.android.play:engage 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'
}

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 1: fornisci i dati dell'entità

L'SDK ha definito diverse entità per rappresentare ogni tipo di elemento. Per la categoria Ascolta vengono supportate le seguenti entità:

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

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

MusicAlbumEntity

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

Attributo	Requisito	Notes
Nome	Obbligatorie	Il titolo dell'album musicale.
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine. Per indicazioni, consulta le specifiche delle immagini.
URI pagina informazioni	Obbligatorie	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	Obbligatorie	Elenco degli artisti presenti 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	Deve contenere massimo 200 caratteri, se fornito.
Numero brani	Facoltativo	Il numero di brani dell'album musicale.
Generi	Facoltativo	Elenco dei generi presenti nell'album musicale.
Formato dell'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 presentano un avviso di avvertenza genitoriale 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 dell'epoca.
Durata	Facoltativo	La durata dell'album in millisecondi.
Data/ora ultimo coinvolgimento	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi dell'epoca
Percentuale di avanzamento completato	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Numero intero compreso tra 0 e 100

MusicArtistEntity

L'oggetto MusicArtistEntity rappresenta un arista musicale (ad esempio, Adele).

Attributo	Requisito	Notes
Nome	Obbligatorie	Nome dell'artista musicale.
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine. Per indicazioni, consulta le specifiche delle immagini.
URI pagina informazioni	Obbligatorie	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 provider. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti
Descrizione	Facoltativo	Deve contenere massimo 200 caratteri, se fornito.
Data/ora ultimo coinvolgimento	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi dell'epoca

MusicTrackEntity

L'oggetto MusicTrackEntity rappresenta una traccia musicale (ad esempio, Yellow dei Coldplay).

Attributo	Requisito	Notes
Nome	Obbligatorie	Titolo della traccia musicale.
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine. Per indicazioni, consulta le specifiche delle immagini.
URI di riproduzione	Obbligatorie	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
URI pagina informazioni	Facoltativo	Un link diretto all'app del fornitore per i dettagli sulla traccia musicale. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti
Descrizione	Facoltativo	Deve contenere massimo 200 caratteri, se fornito.
Durata	Facoltativo	La durata della traccia in millisecondi.
Album	Facoltativo	Il nome dell'album a cui appartiene il brano.
Artisti	Obbligatorie	Elenco di artisti per la traccia musicale.
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 presentano un avviso di avvertenza genitoriale devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con un tag "E".
Data/ora ultimo coinvolgimento	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi dell'epoca
Percentuale di avanzamento completato	Facoltativo	Opzione consigliata per gli elementi 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	Notes
Nome	Obbligatorie	Titolo del video musicale.
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine. Per indicazioni, consulta le specifiche delle immagini.
URI di riproduzione	Obbligatorie	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 pagina 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	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 della traccia.
Descrizione	Facoltativo	Deve contenere massimo 200 caratteri, se fornito.
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 presentano un avviso di avvertenza genitoriale devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con un tag "E".
Data/ora ultimo coinvolgimento	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi dell'epoca
Percentuale di avanzamento completato	Facoltativo	Opzione consigliata per gli elementi 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	Notes
Nome	Obbligatorie	Titolo della playlist.
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine. Per indicazioni, consulta le specifiche delle immagini.
URI di riproduzione	Obbligatorie	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 pagina 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.
Numero brani	Facoltativo	Il numero di brani contenuti nella playlist musicale.
Descrizione	Facoltativo	Deve contenere massimo 200 caratteri, se fornito.
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 presentano un avviso di avvertenza genitoriale devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con un tag "E".
Data/ora ultimo coinvolgimento	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi dell'epoca
Percentuale di avanzamento completato	Facoltativo	Opzione consigliata per gli elementi 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	Notes
Nome	Obbligatorie	Titolo della serie di podcast.
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine. Per indicazioni, consulta le specifiche delle immagini.
URI pagina informazioni	Obbligatorie	Un link diretto all'app del provider 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
Numero di puntate	Facoltativo	Il numero di puntate della serie di podcast.
Nome produzione	Facoltativo	Il nome della produzione della serie di podcast.
Organizzatori	Facoltativo	Elenco dei presentatori della serie di podcast.
Generi	Facoltativo	Elenco dei generi della serie di podcast.
Scaricato sul dispositivo	Facoltativo	Valore booleano che indica se il podcast è stato scaricato sul dispositivo.
Descrizione	Facoltativo	Deve contenere massimo 200 caratteri, se fornito.
Esplicito	Facoltativo	Un valore booleano che indica se i contenuti sono espliciti o meno Gli elementi che contengono materiale esplicito o presentano un avviso di avvertenza genitoriale devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con un tag "E".
Data/ora ultimo coinvolgimento	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi dell'epoca

PodcastEpisodeEntity

L'oggetto PodcastEpisodeEntity rappresenta una serie di podcast (ad esempio Spark Bird, Episode 754: This American Life).

Attributo	Requisito	Notes
Nome	Obbligatorie	Titolo della puntata del podcast.
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine. Per indicazioni, consulta le specifiche delle immagini.
URI di riproduzione	Obbligatorie	Un link diretto che avvia la riproduzione della puntata del podcast nell'app del provider. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti
Titolo della serie di produzione	Obbligatorie	Il nome della serie di podcast a cui appartiene la puntata.
Durata	Obbligatorie	La durata della puntata del podcast in millisecondi.
Data di pubblicazione	Obbligatorie	Data di pubblicazione del podcast (in millisecondi dell'epoca)
URI pagina 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 produzione	Facoltativo	Il nome della produzione della serie di podcast.
Indice puntata	Facoltativo	L'indice della puntata della serie (il primo indice è 1).
Organizzatori	Facoltativo	L'elenco dei presentatori 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	Deve contenere massimo 200 caratteri, se fornito.
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 presentano un avviso di avvertenza genitoriale devono essere impostati su TRUE. Gli elementi espliciti vengono visualizzati con un tag "E".
Ascolta il tipo successivo	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione TYPE_CONTINUA - Riprendi un elemento audio non completato. TYPE_NEXT: continua su un nuovo argomento di una serie. TYPE_NEW: nuova uscita.
Data/ora ultimo coinvolgimento	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi dell'epoca
Percentuale di avanzamento completato	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Numero intero compreso tra 0 e 100

LiveRadioStationEntity

L'oggetto LiveRadioStationEntity rappresenta una stazione radio dal vivo (ad esempio, 98.1 The Breeze).

Attributo	Requisito	Notes
Nome	Obbligatorie	Titolo della stazione radio in diretta.
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine. Per indicazioni, consulta le specifiche delle immagini.
URI di riproduzione	Obbligatorie	Un link diretto che avvia la riproduzione della stazione radio nell'app del provider. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti
URI pagina 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 con cui viene trasmessa la stazione radio (ad esempio, "98.1 FM").
Mostra titolo	Facoltativo	Il programma attualmente in riproduzione sulla stazione radio.
Organizzatori	Facoltativo	Elenco degli host della stazione radio.
Descrizione	Facoltativo	Deve contenere massimo 200 caratteri, se fornito.
Data/ora ultimo coinvolgimento	Facoltativo	Opzione consigliata per gli elementi nel cluster di continuazione. Può essere utilizzato per il ranking. In millisecondi dell'epoca

AudiobookEntity

L'oggetto AudiobookEntity rappresenta un audiolibro (ad esempio, l'audiolibro di Becoming di Michelle Obama).

Attributo	Requisito	Notes
Nome	Obbligatorie
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine. Per indicazioni, consulta le specifiche delle immagini.
Autore	Obbligatorie	È necessario specificare almeno un nome di autore.
Narratore	Obbligatorie	Devi specificare il nome di almeno un narratore.
URI link di azione	Obbligatorie	Il link diretto all'app del fornitore per l'audiolibro. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti
Data di uscita	Facoltativo	Se fornito, in millisecondi epoch.
Descrizione	Facoltativo	Deve contenere massimo 200 caratteri, se fornito.
Prezzo	Facoltativo	Testo libero
Durata	Facoltativo	Deve essere un valore positivo, se fornito.
Genere	Facoltativo	Elenco dei generi associati al libro.
Nome serie	Facoltativo	Nome della serie a cui appartiene l'audiolibro (ad esempio, Harry Potter).
Indice delle unità della 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, il valore dovrebbe essere 3.
Continua tipo di libro	Facoltativo	TYPE_CONTINUA - Riprendi un libro da completare. TYPE_NEXT: continua su un nuovo argomento di una serie. TYPE_NEW: nuova uscita.
Data/ora ultimo coinvolgimento	Obbligatoria condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster di continuazione. In millisecondi dell'epoca.
Percentuale di avanzamento completata	Obbligatoria condizionalmente	Deve essere fornito quando l'elemento si trova nel cluster di continuazione. Gli audiolibri *appena* acquisiti possono far parte del cluster di lettura continua. Il valore deve essere maggiore di 0 e minore di 100.
DisplayTimeWindow: imposta una finestra temporale per la visualizzazione di un contenuto in superficie
Timestamp inizio	Facoltativo	Il timestamp dell'epoca dopo il quale i contenuti dovrebbero essere mostrati in superficie. Se non viene configurato, i contenuti sono idonei a essere mostrati in evidenza. In millisecondi dell'epoca.
Timestamp fine	Facoltativo	Il timestamp dell'epoca dopo il quale i contenuti non vengono più mostrati in superficie. Se non viene configurato, i contenuti sono idonei a essere mostrati in evidenza. In millisecondi dell'epoca.

Specifiche per le immagini

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

Proporzioni	Requisito	Numero minimo di pixel	Numero consigliato di pixel
Quadrato (1 x 1)	Obbligatorie	300x300	1200x1200
Orizzontale (1,91 x 1)	Facoltativo	600x314	1200x628
Verticale (4 x 5)	Facoltativo	480x600	960x1200

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

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

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

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

publishRecommendationClusters

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

Importante: le API di pubblicazione sono API upsert e sostituiscono i contenuti esistenti. Non chiamare delete e pubblicare successivamente le API per sostituire i contenuti, come fanno le API di pubblicazione intrinsecamente.

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

Importante: le API di pubblicazione sono API upsert e sostituiscono i contenuti esistenti. Non chiamare delete e pubblicare successivamente le API per sostituire i contenuti, come fanno le API di pubblicazione intrinsecamente.

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

Importante: le API di pubblicazione sono API upsert e sostituiscono i contenuti esistenti. Non chiamare delete e pubblicare successivamente le API per sostituire i contenuti, come fanno le API di pubblicazione intrinsecamente.

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, 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

Importante: le API di pubblicazione sono API upsert e sostituiscono i contenuti esistenti. Non chiamare delete e pubblicare successivamente le API per sostituire i contenuti, come fanno le API di pubblicazione intrinsecamente.

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Quando il servizio riceve la richiesta, 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.

Importante: le API di eliminazione dovrebbero essere richiamate solo quando non ci sono contenuti da pubblicare. Non chiamare "delete" e pubblicare successivamente le API per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta engagement-developers@ prima di utilizzare le API di eliminazione.

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.

Nota: questa API è disponibile a partire dalla versione 1.1.0.

deleteFeaturedCluster

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

Importante: le API di eliminazione dovrebbero essere richiamate solo quando non ci sono contenuti da pubblicare. Non chiamare "delete" e pubblicare successivamente le API per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta engagement-developers@ prima di utilizzare le API di eliminazione.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

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

Nota: questa API è disponibile a partire dalla versione 1.1.0.

deleteContinuationCluster

Questa API viene utilizzata per eliminare il contenuto del cluster di continuazione.

Importante: le API di eliminazione dovrebbero essere richiamate solo quando non ci sono contenuti da pubblicare. Non chiamare "delete" e pubblicare successivamente le API per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta engagement-developers@ prima di utilizzare le API di eliminazione.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

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

Nota: questa API è disponibile a partire dalla versione 1.1.0.

deleteUserManagementCluster

Questa API viene utilizzata per eliminare il contenuto del cluster UserAccountManagement.

Importante: le API di eliminazione dovrebbero essere richiamate solo quando non ci sono contenuti da pubblicare. Non chiamare "delete" e pubblicare successivamente le API per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta engagement-developers@ prima di utilizzare le API di eliminazione.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

Nota: questa API è disponibile a partire dalla versione 1.1.0.

deleteClusters

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

Importante: le API di eliminazione dovrebbero essere richiamate solo quando non ci sono contenuti da pubblicare. Non chiamare "delete" e pubblicare successivamente le API per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta engagement-developers@ prima di utilizzare le API di eliminazione.

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 eseguire 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	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 utilizzando Context.registerReceiver(). Ciò consente la comunicazione dalle applicazioni ancora presenti in memoria.

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 file AndroidManifest.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 chiamata publishRecommendationClusters quando ricevi questo intent.
• com.google.android.engage.action.PUBLISH_FEATURED È consigliabile avviare una chiamata publishFeaturedCluster quando ricevi questo intent.
• com.google.android.engage.action.PUBLISH_CONTINUATION Ti consigliamo di avviare una chiamata publishContinuationCluster 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 [e-mail] in caso di domande durante la procedura di integrazione. Il nostro team ti risponderà appena possibile.

Passaggi successivi

Una volta completata l'integrazione, i passaggi successivi sono i seguenti:

• Invia un'email all'indirizzo [e-mail] e allega l'APK integrato pronto per i test di Google.
• Google eseguirà una verifica e un controllo interno per assicurarsi che l'integrazione funzioni come previsto. Se sono necessarie modifiche, Google ti contatterà con i dettagli necessari.
• Quando il test sarà completo e non saranno necessarie modifiche, Google ti contatterà per informarti che puoi iniziare a pubblicare l'APK aggiornato e integrato sul Play Store.
• Una volta che Google avrà confermato che l'APK aggiornato è stato pubblicato sul Play Store, i tuoi cluster Consigli, In primo piano e Continuazione verranno pubblicati e saranno visibili agli utenti.