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

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, Entertainment Space e il Play Store. L'integrazione aggiunge meno di 50 KB (compressi) all'APK medio e richiede agli sviluppatori circa una settimana di tempo. Scopri di più sul nostro sito aziendale.

Questa guida contiene le istruzioni per i partner sviluppatori per la pubblicazione di contenuti di lettura (eBook, audiolibri, fumetti/manga) sulle piattaforme di contenuti 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 di un singolo 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 un ebook, un audiolibro, una serie di libri 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 Continua mostra i libri non terminati di più partner sviluppatori in un unico raggruppamento dell'interfaccia utente. A ogni partner sviluppatore sarà consentito di 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 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. Ci sarà un unico cluster In primo piano, che viene visualizzato nella parte superiore della UI con un posizionamento prioritario sopra tutti i cluster di consigli. A ogni partner sviluppatore sarà consentito 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 Lettura:

  1. EbookEntity
  2. AudiobookEntity
  3. BookSeriesEntity

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

EbookEntity

L'oggetto EbookEntity rappresenta un ebook (ad esempio, l'ebook 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'ebook.

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

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
Numero di pagine Facoltativo Se specificato, deve essere un numero intero positivo.
Genere Facoltativo Elenco dei generi associati al libro.
Nome serie Facoltativo Il nome della serie a cui appartiene l'ebook (ad esempio, Harry Potter).
Indice unità serie Facoltativo L'indice dell'ebook nella serie, dove 1 è il primo ebook 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.

Gli ebook acquisiti *di recente* possono far parte del cluster Continua a leggere.

In millisecondi dall'epoca.

Percentuale di avanzamento completata Obbligatorio condizionalmente

Deve essere fornito quando l'articolo si trova nel cluster Continuazione.

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.

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.

BookSeriesEntity

L'oggetto BookSeriesEntity rappresenta una serie di libri (ad esempio, la serie di libri di Harry Potter, che ha 7 libri).

Attributo Requisito Note
Nome Obbligatorio
Immagini poster Obbligatorio Devi fornire almeno un'immagine. Consulta le specifiche delle immagini per indicazioni.
Autore Obbligatorio Deve essere presente almeno un nome dell'autore.
URI del link all'azione Obbligatorio

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

Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

Numero di libri Obbligatorio Numero di libri della serie.
Descrizione Facoltativo Se fornito, non deve superare i 200 caratteri.
Genere Facoltativo Elenco dei generi associati al libro.
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.

Le serie di libri *acquisite 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%.

Esempio

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("Reconnect with yourself")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .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(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

Java

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_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 utilizzando Context.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 file AndroidManifest.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 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_CONTINUATIONIt is recommended to start apublishContinuationCluster` 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.