Questa pagina è stata tradotta dall'API Cloud Translation.

Engage SDK Shopping: 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 propri contenuti di Shopping, utilizzando l'SDK Engage per completare sia questa nuova area di superficie sia piattaforme Google esistenti come Entertainment Space.

Dettagli integrazione

Di seguito sono riportati i dettagli dell'integrazione:

Terminologia

Questa integrazione include i seguenti cinque tipi di cluster: Consiglio, In primo piano, Carrello degli acquisti, Lista della spesa e Riordina.

I cluster di consigli mostrano suggerimenti di acquisto personalizzati da un singolo partner di sviluppo. Questi consigli possono essere personalizzati in base all'utente o generalizzati (ad esempio, articoli di tendenza). Usali per mettere in evidenza prodotti, eventi, saldi, promozioni e abbonamenti nella maniera che ritieni più opportuna.

I consigli hanno la seguente struttura:
- Cluster di suggerimenti:una visualizzazione dell'interfaccia utente che contiene un gruppo di suggerimenti dello stesso sviluppatore partner.
- ShoppingEntity:un oggetto che rappresenta un singolo articolo in un cluster.
Il cluster In primo piano mostra l'elemento hero scelto ShoppingEntity da molti partner di sviluppatori in un unico raggruppamento dell'interfaccia utente. È presente un unico cluster In primo piano, visualizzato nella parte superiore dell'interfaccia utente, con un posizionamento di priorità sopra tutti i cluster di suggerimenti. A ogni sviluppatore partner è consentito pubblicare una singola ShoppingEntity nel cluster In primo piano.
Il cluster Carrello degli acquisti mostra un'anteprima dei carrelli degli acquisti di molti sviluppatori partner in un unico raggruppamento nell'interfaccia utente, incoraggiando gli utenti a completare i carrelli in sospeso. È presente un unico cluster di carrello degli acquisti, visualizzato nella parte superiore dell'interfaccia utente, con un posizionamento della priorità sopra tutti i cluster di suggerimenti. Ogni sviluppatore partner può trasmettere un singolo ShoppingCart nel cluster del carrello degli acquisti.

Il tuo carrello degli acquisti ha la seguente struttura:
- Cluster carrello degli acquisti:una visualizzazione UI che contiene un gruppo di anteprime del carrello degli acquisti di molti sviluppatori partner.
- ShoppingCart: un oggetto che rappresenta l'anteprima del carrello degli acquisti per un singolo partner di sviluppo, da visualizzare nel cluster del carrello degli acquisti. L'attributo ShoppingCart deve indicare il numero totale di articoli nel carrello e può anche includere immagini per alcuni articoli nel carrello dell'utente.
Il cluster Lista della spesa mostra un'anteprima delle liste della spesa di più sviluppatori partner in un unico raggruppamento nell'interfaccia utente, invitando gli utenti a tornare all'app corrispondente per aggiornare e completare i propri elenchi. Esiste un solo cluster di liste della spesa.
Il cluster Riordina mostra un'anteprima degli ordini precedenti di più sviluppatori partner in un unico raggruppamento di UI, invitando gli utenti a riordinare. Esiste un unico cluster Riordina.
- Il cluster di riordinamento deve mostrare il conteggio totale degli elementi nell'ordine precedente dell'utente e deve includere anche uno dei seguenti elementi:
  - Immagini di X articoli nell'ordine precedente dell'utente.
  - Etichette per X articoli nell'ordine precedente dell'utente.

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'
}

Per maggiori informazioni, consulta la sezione Visibilità dei pacchetti in Android 11.

Riepilogo

Il design si basa sull'implementazione di un servizio associato.

I dati che un client può pubblicare sono soggetti ai seguenti limiti per tipi di cluster diversi:

Tipo di cluster	Limiti del cluster	Limiti massimi di entità in un cluster
Cluster di suggerimenti	Massimo 5	Al massimo 25 `ShoppingEntity`
Cluster in primo piano	Al massimo 1	Al massimo 1 `ShoppingEntity`
Cluster di carrelli degli acquisti	Al massimo 1	Al massimo 1 `ShoppingCart`
Cluster della lista della spesa	Al massimo 1	Al massimo 1 `ShoppingListEntity`
Riordina cluster Shopping	Al massimo 1	Al massimo 1 `ReorderEntity`

Passaggio 1: fornisci i dati dell'entità

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

ShoppingEntity
ShoppingCart
ShoppingList
Reorder

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

`ShoppingEntity`

L'oggetto ShoppingEntity rappresenta un prodotto, una promozione, un deal, un abbonamento o un evento che gli sviluppatori partner vogliono pubblicare.

`ShoppingEntity`

Attributo	Requisito	Descrizione	Formato
Immagini poster	Obbligatorie	Devi fornire almeno un'immagine.	Per istruzioni, consulta la sezione Specifiche delle immagini.
URI azione	Obbligatorie	Il link diretto alla pagina nell'app che mostra i dettagli dell'entità. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti	URI
Titolo	Facoltativo	Il nome dell'entità.	Testo libero Dimensione del testo consigliata: inferiore a 90 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)
Prezzo - attuale	Obbligatoria condizionalmente	Il prezzo corrente dell'entità. Deve essere indicato se viene indicato un prezzo barrato.	Testo libero
Prezzo - barrato	Facoltativo	Il prezzo originale dell'entità, barrato nell'interfaccia utente.	Testo libero
Callout	Facoltativo	Callout per mostrare una promozione, un evento o un aggiornamento per l'entità, se disponibile.	Testo libero Dimensioni del testo consigliate: meno di 45 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)
Callout con clausole	Facoltativo	Testo in caratteri piccoli per il callout.	Testo libero Dimensioni del testo consigliate: meno di 45 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)
(Facoltativo) Valutazione. Nota: tutte le valutazioni vengono visualizzate utilizzando il nostro sistema di valutazione a stelle standard.
Valutazione - valore massimo	Obbligatorio	Il valore massimo della scala di valutazione. Deve essere fornito se viene fornito anche il valore attuale della valutazione.	Numero >= 0,0
Valutazione - valore attuale	Obbligatorio	Il valore attuale della valutazione dell'entità. Deve essere fornito se viene fornito anche un valore massimo della valutazione.	Numero >= 0,0
Valutazione - conteggio	Facoltativo	Il conteggio delle valutazioni per l'entità.	Stringa
(Facoltativo) 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.	Timestamp epoca in millisecondi
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.	Timestamp epoca in millisecondi

`ShoppingCart`

Attributo	Requisito	Descrizione	Formato
URI azione	Obbligatorie	Il link diretto al carrello degli acquisti nell'app del partner. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti	URI
Numero di elementi	Obbligatorie	Il numero di articoli (non solo il numero di prodotti) nel carrello degli acquisti. Ad esempio: se nel carrello sono presenti 3 magliette identiche e un cappello, questo numero deve essere 4.	Numero intero >= 1
Testo dell'azione	Facoltativo	Il testo dell'invito all'azione relativo al pulsante nel carrello degli acquisti (ad esempio La tua borsa della spesa). *Se lo sviluppatore non fornisce il testo dell'azione, l'impostazione predefinita è Visualizza carrello.* Questo attributo è supportato a partire dalla versione 1.1.0.	Stringa
Titolo	Facoltativo	Il titolo del carrello (ad es. La tua borsa della spesa). *Se lo sviluppatore non fornisce alcun titolo, Il tuo carrello* è l'impostazione predefinita.**	Testo libero Dimensioni del testo consigliate: meno di 25 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)
Immagini del carrello	Facoltativo	Immagini di ogni prodotto nel carrello. È possibile fornire fino a 10 immagini in ordine di priorità; il numero effettivo di immagini visualizzate dipende dal fattore di forma del dispositivo.	Per istruzioni, consulta la sezione Specifiche delle immagini.
Etichette elemento	Facoltativo	L'elenco di etichette degli articoli presenti nella lista della spesa. Il numero effettivo di etichette visualizzate dipende dal fattore di forma del dispositivo.	Elenco di etichette di testo libero Dimensione del testo consigliata: inferiore a 20 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)
(Facoltativo) 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.	Timestamp epoca in millisecondi
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.	Timestamp epoca in millisecondi

`ShoppingList`

Attributo	Requisito	Descrizione	Formato
URI azione	Obbligatorie	Il link diretto alla lista della spesa nell'app del partner. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti	URI
Numero di elementi	Obbligatorie	Il numero di articoli nella lista della spesa.	Numero intero >= 1
Titolo	Facoltativo	Il titolo della lista, ad esempio La tua lista della spesa. *Se lo sviluppatore non fornisce alcun titolo, Lista della spesa* è l'impostazione predefinita.**	Testo libero Dimensioni del testo consigliate: meno di 25 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)
Etichette elemento	Obbligatorie	L'elenco di etichette degli articoli presenti nella lista della spesa. È necessario fornire almeno un'etichetta e specificare fino a 10 etichette in ordine di priorità; il numero effettivo di etichette visualizzate dipende dal fattore di forma del dispositivo.	Elenco di etichette di testo libero Dimensione del testo consigliata: inferiore a 20 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)

`ShoppingReorderCluster`

Attributo	Requisito	Descrizione	Formato
URI azione	Obbligatorie	Il link diretto da riordinare nell'app del partner. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti	URI
Testo dell'azione	Facoltativo	Il testo dell'invito all'azione del pulsante sul Riordina (ad es. Ordina di nuovo). *Se lo sviluppatore non fornisce il testo delle azioni, Riordina* è l'impostazione predefinita.** Questo attributo è supportato a partire dalla versione 1.1.0.	Stringa
Numero di elementi	Obbligatorie	Il numero di articoli (non solo il numero di prodotti) nell'ordine precedente. Ad esempio, se nell'ordine precedente erano presenti 3 caffè piccoli e 1 croissant, questo numero deve essere 4.	Numero intero >= 1
Titolo	Obbligatorie	Il titolo dell'articolo di riordinamento.	Testo libero Dimensione del testo consigliata: inferiore a 40 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)
Etichette elemento	Facoltativo Se non vengono fornite, è necessario fornire le immagini poster.	L'elenco di etichette degli elementi per l'ordine precedente. È possibile fornire fino a 10 etichette in ordine di priorità; il numero effettivo di etichette visualizzate dipende dal fattore di forma del dispositivo.	Elenco di testo libero Dimensioni del testo consigliate per etichetta: inferiore a 20 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)
Immagini poster	Facoltativo Se non vengono fornite, è necessario fornire le etichette degli articoli.	Immagini degli articoli nell'ordine precedente. È possibile fornire fino a 10 immagini in ordine di priorità; il numero effettivo di immagini visualizzate dipende dal fattore di forma del dispositivo.	Per istruzioni, consulta la sezione Specifiche delle immagini.

Specifiche per le immagini

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

Proporzioni	Numero minimo di pixel	Numero consigliato di pixel
Quadrato (1 x 1) Preferito per i cluster non in primo piano	300x300	1200x1200
Orizzontale (1,91 x 1) Preferito per i cluster in primo piano	600x314	1200x628
Verticale (4 x 5)	480x600	960x1200

Proporzioni

Numero minimo di pixel

Numero consigliato di pixel

Quadrato (1 x 1)

Preferito per i cluster non in primo piano

300x300

1200x1200

Orizzontale (1,91 x 1)

Preferito per i cluster in primo piano

600x314

1200x628

Verticale (4 x 5)

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%.
Utilizza uno sfondo trasparente in modo che l'immagine possa essere visualizzata correttamente nelle impostazioni del tema scuro e chiaro.

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

AppEngageShoppingClient è responsabile della pubblicazione dei cluster acquisti.

Le seguenti API sono esposte per pubblicare i cluster nel client:

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishShoppingCart
publishShoppingList
publishShoppingReorderCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteShoppingCartCluster
deleteShoppingListCluster
deleteShoppingReorderCluster
deleteUserManagementCluster
deleteClusters

`isServiceAvailable`

Questa API viene utilizzata per verificare se il servizio è disponibile per l'integrazione e se i contenuti possono essere presentati sul dispositivo.

Kotlin


client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java


client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content
          // publish calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

`publishRecommendationClusters`

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

Un oggetto RecommendationCluster può avere i seguenti attributi:

Attributo	Requisito	Descrizione
Elenco di ShoppingEntity	Obbligatorie	Un elenco di oggetti ShoppingEntity che costituiscono i suggerimenti per questo cluster di suggerimenti.
Titolo	Obbligatorie	Il titolo del cluster di suggerimenti. Dimensioni del testo consigliate: meno di 25 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)
URI azione	Facoltativo	Il link diretto alla pagina dell'app del partner in cui gli utenti possono visualizzare l'elenco completo dei suggerimenti. Nota: puoi utilizzare i link diretti per l'attribuzione. Consulta queste domande frequenti

Attributo

Requisito

Descrizione

Elenco di ShoppingEntity

Obbligatorie

Un elenco di oggetti ShoppingEntity che costituiscono i suggerimenti per questo cluster di suggerimenti.

Titolo

Obbligatorie

Il titolo del cluster di suggerimenti.

Dimensioni del testo consigliate: meno di 25 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)

URI azione

Facoltativo

Il link diretto alla pagina dell'app del partner in cui gli utenti possono visualizzare l'elenco completo dei suggerimenti.

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

Kotlin


client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build())

Java


client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build());

Quando il servizio riceve la richiesta, le seguenti azioni vengono eseguite nell'ambito di una transazione:

Tutti i dati esistenti del cluster di suggerimenti vengono rimossi.
I dati della richiesta vengono analizzati e archiviati in nuovi cluster di suggerimenti.

In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto lo stato esistente.

`publishFeaturedCluster`

Questa API viene utilizzata per pubblicare un oggetto 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, 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.

`publishShoppingCart`

Questa API viene utilizzata per pubblicare un oggetto ShoppingCartCluster.

Kotlin


client.publishShoppingCart(
            PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java


client.publishShoppingCart(
            new PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Quando il servizio riceve la richiesta, le seguenti azioni vengono eseguite nell'ambito di una transazione:

I dati di ShoppingCart esistenti dal partner sviluppatore verranno rimossi.
I dati della richiesta vengono analizzati e archiviati nel cluster del carrello degli acquisti aggiornato.

In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto lo stato esistente.

`publishShoppingList`

Questa API viene utilizzata per pubblicare un oggetto FoodShoppingList.

Kotlin


client.publishFoodShoppingList(
            PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build())

Java


client.publishFoodShoppingList(
            new PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    new FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

Quando il servizio riceve la richiesta, le seguenti azioni vengono eseguite nell'ambito di una transazione:

I dati di FoodShoppingList esistenti dal partner sviluppatore verranno rimossi.
I dati della richiesta vengono analizzati e archiviati nel cluster della lista della spesa aggiornato.

In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto lo stato esistente.

`publishShoppingReorderCluster`

Questa API viene utilizzata per pubblicare un oggetto ShoppingReorderCluster.

Kotlin


client.publishShoppingReorderCluster(
            PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build())

Java


client.publishShoppingReorderCluster(
            new PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    new ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build());

Quando il servizio riceve la richiesta, le seguenti azioni vengono eseguite nell'ambito di una transazione:

I dati di ShoppingReorderCluster esistenti dal partner sviluppatore verranno rimossi.
I dati della richiesta vengono analizzati e archiviati nel cluster Riordina aggiornato.

In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto lo stato esistente.

`publishUserAccountManagementRequest`

Questa API viene utilizzata per pubblicare una scheda di accesso . L'azione di accesso indirizza gli utenti alla pagina di accesso dell'app affinché quest'ultima possa pubblicare contenuti (o fornire contenuti più personalizzati)

I seguenti metadati fanno parte della scheda di accesso:

Attributo	Requisito	Descrizione
URI azione	Obbligatorio	Link diretto all'azione (ad esempio, consente di accedere alla pagina di accesso dell'app)
Immagine	Facoltativo: se non viene specificato, è necessario specificare il titolo	Immagine mostrata nella scheda Immagini con proporzioni 16:9 con una risoluzione di 1264x712
Titolo	Facoltativo - Se non viene fornita, è necessario fornire l'immagine	Titolo sulla scheda
Testo dell'azione	Facoltativo	Testo visualizzato nell'invito all'azione (ad es. Accedi)
Sottotitolo	Facoltativo	Sottotitolo facoltativo sulla scheda

Kotlin


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

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

Java


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

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

Quando il servizio riceve la richiesta, le seguenti azioni vengono eseguite nell'ambito di una transazione:

I dati UserAccountManagementCluster esistenti del partner sviluppatore verranno rimossi.
I dati della richiesta vengono analizzati e archiviati nel cluster UserAccountManagementCluster aggiornato.

In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto lo stato esistente.

`updatePublishStatus`

Se per qualsiasi motivo aziendale interno non viene pubblicato nessuno dei cluster, ti consigliamo vivamente di aggiornare lo stato di pubblicazione utilizzando l'API updatepublishStatus. Questo è importante perché :

Fornire lo stato in tutti gli scenari, anche quando i contenuti vengono pubblicati (STATUS == PUBBLICATO), è fondamentale per completare le dashboard che utilizzano questo stato esplicito per comunicare lo stato e altre metriche dell'integrazione.
Se non vengono pubblicati contenuti, ma lo stato dell'integrazione non funziona (STATUS == NOT_PUBED), Google può evitare di attivare avvisi nelle dashboard di integrità dell'app. Conferma che i contenuti non sono stati pubblicati a causa di una situazione prevista dal punto di vista del fornitore.
Aiuta gli sviluppatori a fornire insight sul momento in cui i dati vengono pubblicati o meno.
Google potrebbe utilizzare i codici di stato per sollecitare l'utente a eseguire determinate azioni nell'app, in modo da visualizzarne i contenuti o superarli.

Di seguito sono elencati i codici di stato di pubblicazione idonei :

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

Se i contenuti non vengono pubblicati perché un utente non ha eseguito l'accesso, Google consiglia di pubblicare la scheda di accesso. Se per qualsiasi motivo i provider non riescono a pubblicare la scheda di accesso, ti consigliamo di chiamare l'API updatepublishStatus con il codice di stato NOT_PUBBLICAZIONE_REQUIRES_SIGN_IN

Kotlin


client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java


client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

`deleteRecommendationClusters`

Questa API viene utilizzata per eliminare il contenuto dei cluster di suggerimenti.

Kotlin


client.deleteRecommendationClusters()

Java


client.deleteRecommendationClusters();

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

`deleteFeaturedCluster`

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

Kotlin


client.deleteFeaturedCluster()

Java


client.deleteFeaturedCluster();

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

`deleteShoppingCartCluster`

Questa API viene utilizzata per eliminare i contenuti del cluster del carrello degli acquisti.

Kotlin


client.deleteShoppingCartCluster()

Java


client.deleteShoppingCartCluster();

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

`deleteShoppingListCluster`

Questa API viene utilizzata per eliminare i contenuti del cluster della lista della spesa.

Kotlin


client.deleteShoppingListCluster()

Java


client.deleteShoppingListCluster();

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

`deleteShoppingReorderCluster`

Questa API viene utilizzata per eliminare i contenuti del cluster di riordinamento Shopping.

Kotlin


client.deleteShoppingReorderCluster()

Java


client.deleteShoppingReorderCluster();

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

`deleteUserManagementCluster`

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

Kotlin


client.deleteUserManagementCluster()

Java


client.deleteUserManagementCluster();

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

`deleteClusters`

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

Kotlin


client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_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.

Kotlin


client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java


client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

L'errore viene restituito come AppEngageException con la causa inclusa come codice di errore.

Codice di errore	Nota
`SERVICE_NOT_FOUND`	Il servizio non è disponibile sul dispositivo specificato.
`SERVICE_NOT_AVAILABLE`	Il servizio è disponibile sul dispositivo in questione, ma non al momento della chiamata (ad esempio, è disabilitato esplicitamente).
`SERVICE_CALL_EXECUTION_FAILURE`	Esecuzione dell'attività non riuscita a causa di problemi di organizzazione in thread. In questo caso, sarà possibile riprovare.
`SERVICE_CALL_PERMISSION_DENIED`	Il chiamante non è autorizzato a effettuare la chiamata di servizio.
`SERVICE_CALL_INVALID_ARGUMENT`	La richiesta contiene dati non validi (ad esempio, più del numero consentito di cluster).
`SERVICE_CALL_INTERNAL`	È presente un errore sul lato servizio.
`SERVICE_CALL_RESOURCE_EXHAUSTED`	La chiamata al servizio viene effettuata troppo spesso.

Passaggio 3: gestisci gli intent di trasmissione

Oltre a effettuare chiamate alla Content API per la pubblicazione tramite un job, è anche necessario configurare un BroadcastReceiver per ricevere la richiesta di pubblicazione di contenuti.

L'obiettivo degli intent di trasmissione è principalmente la riattivazione dell'app e la forzatura della sincronizzazione dei dati. Gli intent di trasmissione non sono progettati per essere inviati molto di frequente. Viene attivato solo quando il servizio Engage determina che i contenuti potrebbero essere obsoleti (ad esempio, una settimana fa). In questo modo, si può avere più sicurezza che l'utente possa avere un'esperienza con i contenuti aggiornati, anche se l'applicazione non è stata eseguita per un lungo periodo di tempo.

BroadcastReceiver deve essere configurato nei due modi seguenti:

Registra dinamicamente un'istanza della classe BroadcastReceiver utilizzando Context.registerReceiver(). Ciò consente la comunicazione dalle applicazioni ancora presenti in memoria.

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION
  // broadcast is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is
  // received
  // Trigger shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast
  // is received
  // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast
  // is received
  // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART))

// Register Shopping List Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST))

// Register Reorder Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER))
}

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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast is
// received

// Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast is
// received

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER 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 Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART));

// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_LIST));

// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER));

}

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.shopping.PUBLISH_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
      </intent-filter>
   </receiver>
</application>

I seguenti intent vengono inviati dal servizio:

com.google.android.engage.action.PUBLISH_RECOMMENDATION È consigliabile avviare una chiamata publishRecommendationClusters quando viene ricevuto questo intent.
com.google.android.engage.action.PUBLISH_FEATURED Si consiglia di avviare una chiamata publishFeaturedCluster quando viene ricevuto questo intent.
com.google.android.engage.action.shopping.PUBLISH_SHOPPING_CART Si consiglia di avviare una chiamata publishShoppingCart quando viene ricevuto questo intent.
com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST Si consiglia di avviare una chiamata publishShoppingList quando viene ricevuto questo intent.
com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER Si consiglia di avviare una chiamata publishReorderCluster quando viene ricevuto questo intent.

Flusso di lavoro di integrazione

Per una guida passo passo sulla verifica dell'integrazione dopo il completamento, consulta Flusso di lavoro dell'integrazione per gli sviluppatori sul coinvolgimento.

Domande frequenti

Consulta le Domande frequenti sull'SDK Engage per le domande frequenti.

Contact

Contatta engagement-developers@google.com in caso di domande durante la procedura di integrazione. Il nostro team risponde il prima possibile.

Passaggi successivi

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

Invia un'email all'indirizzo Engage-developers@google.com e allega l'APK integrato pronto per i test di Google.
Google esegue una verifica ed esamina internamente per assicurarsi che l'integrazione funzioni come previsto. Se sono necessarie modifiche, Google ti contatta fornendoti tutti i dettagli necessari.
Quando il test è completo e non sono necessarie modifiche, Google ti contatta per informarti che puoi iniziare a pubblicare l'APK aggiornato e integrato nel Play Store.
Una volta che Google avrà confermato che l'APK aggiornato è stato pubblicato sul Play Store, i tuoi cluster Consigli, In primo piano e Carrello degli acquisti potrebbero essere pubblicati e visibili agli utenti.