Engage SDK Food: 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 gastronomici, 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 cinque tipi di cluster: Consiglio, In primo piano, Carrello della spesa di cibo, Lista della spesa alimentare e Riordina.

  • I cluster di consigli mostrano suggerimenti personalizzati relativi agli alimenti da un singolo sviluppatore partner. Questi consigli possono essere personalizzati per l'utente o generalizzati (ad es. nuovi articoli in offerta). Usali per mostrare ricette, negozi, piatti, generi alimentari e così via.

    • Un cluster di suggerimenti può essere composto da schede ProductEntity, StoreEntity o RecipeEntity, ma non da una combinazione di tipi di entità diversi.
  • Il cluster In primo piano mostra l'elemento hero scelto ProductEntity, StoreEntity o RecipeEntity da molti sviluppatori partner in un unico raggruppamento dell'interfaccia utente. Esiste un unico cluster di funzionalità, che viene visualizzato nella parte superiore dell'interfaccia utente, con un posizionamento della priorità sopra tutti i cluster di suggerimenti. Ogni sviluppatore partner può trasmettere una singola entità di un tipo supportato in In primo piano, con molte entità (potenzialmente di tipi diversi) di più sviluppatori di app nel cluster In primo piano.

  • Il cluster Carrello per la spesa di alimenti mostra un'anteprima dei carrelli della spesa di diversi sviluppatori partner in un unico raggruppamento nell'interfaccia utente, invitando gli utenti a completare i carrelli in sospeso. C'è un solo cluster di carrelli della spesa di cibo.

    • Il cluster del carrello degli acquisti di alimenti deve mostrare il numero totale di articoli nel carrello e può anche includere immagini per X articoli nel carrello dell'utente.
  • Il cluster Lista della spesa di cibo mostra un'anteprima delle liste della spesa di diversi 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 di cibo.

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

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 (ProductEntity, RecipeEntity o StoreEntity)
Cluster in primo piano Al massimo 1 Al massimo 1 (ProductEntity, RecipeEntity o StoreEntity)
Cluster di carrelli della spesa di cibo Al massimo 1 Al massimo 1 ShoppingCartEntity
Cluster di liste della spesa di cibo Al massimo 1 Al massimo 1 ShoppingListEntity
Riordina gli alimenti 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 Alimenti, supportiamo le seguenti persone giuridiche:

  1. ProductEntity
  2. StoreEntity
  3. RecipeEntity
  4. FoodShoppingCart
  5. FoodShoppingList
  6. FoodReorderCluster

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

ProductEntity

L'oggetto ProductEntity rappresenta un singolo articolo (ad esempio un articolo alimentare, un piatto di un ristorante o una promozione) che i partner sviluppatori vogliono pubblicare.

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 del prodotto.

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

URI
Titolo Facoltativo Il nome del prodotto.

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 del prodotto.

Deve essere indicato se viene indicato un prezzo barrato.

Testo libero
Prezzo - barrato Facoltativo Il prezzo originale dell'entità, barrato nella UI. Testo libero
Callout Facoltativo Callout per mostrare una promozione, un evento o un aggiornamento per il prodotto, 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

StoreEntity

L'oggetto StoreEntity rappresenta un singolo negozio che i partner di sviluppo desiderano pubblicare, ad esempio un ristorante o un negozio di alimentari.

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 dello store.

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

URI
Titolo Facoltativo Il nome del negozio.

Testo libero

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

Posizione Facoltativo La sede del negozio.

Testo libero

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

Callout Facoltativo Callout per mostrare una promozione, un evento o un aggiornamento per lo store, 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)

Descrizione Facoltativo Una descrizione del negozio.

Testo libero

Dimensione del testo consigliata: inferiore a 90 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)

Nota: tutte le valutazioni vengono visualizzate utilizzando il nostro sistema di valutazione a stelle standard.
Valutazione - valore massimo Obbligatoria condizionalmente

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 Obbligatoria condizionalmente

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

RecipeEntity

L'oggetto RecipeEntity rappresenta un elemento di formula che i partner di sviluppo vogliono pubblicare.

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 della ricetta.

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

URI
Titolo Facoltativo Il nome della ricetta.

Testo libero

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

Autore Facoltativo L'autore della ricetta.

Testo libero

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

Tempo di cottura/preparazione Facoltativo Il tempo di cottura della ricetta.

Testo libero

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

Callout Facoltativo Callout per mostrare una promozione, un evento o un aggiornamento della ricetta, se disponibile.

Testo libero

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

Categoria Facoltativo La categoria della ricetta.

Testo libero

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

Descrizione Facoltativo Una descrizione della ricetta.

Testo libero

Dimensione del testo consigliata: inferiore a 90 caratteri (il testo troppo lungo potrebbe mostrare dei puntini di sospensione)

Nota: tutte le valutazioni vengono visualizzate utilizzando il nostro sistema di valutazione a stelle standard.
Valutazione - valore massimo Obbligatoria condizionalmente

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 Obbligatoria condizionalmente

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

FoodShoppingCart

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 ci sono 3 arance e 1 mela, questo numero deve essere 4.

Numero intero >= 1
Titolo Facoltativo

Il titolo del carrello (ad esempio Il tuo carrello).

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)

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

FoodShoppingList

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)

FoodReorderCluster

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

300x300 1200x1200
Orizzontale (1,91 x 1) 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).

AppEngageFoodClient è responsabile della pubblicazione di raggruppamenti di alimenti.

Esistono API per pubblicare i cluster nel client:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishFoodShoppingCart
  • publishFoodShoppingList
  • publishReorderCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteFoodShoppingCartCluster
  • deleteFoodShoppingListCluster
  • deleteReorderCluster
  • 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.

Un oggetto RecommendationCluster può avere i seguenti attributi:

Attributo Requisito Descrizione
Elenco di ProductEntity, StoreEntity o RecipeEntity Obbligatorie Un elenco di entità che costituiscono i suggerimenti per questo cluster di suggerimenti. Le entità in un singolo cluster devono essere dello stesso tipo.
Titolo Obbligatorie

Il titolo del cluster di suggerimenti (ad esempio, Grandi risparmi sul menu del Ringraziamento).

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("Big savings on Thanksgiving menu")
                        .build())
                .build())

Java


client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .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.

publishFoodShoppingCart

Questa API viene utilizzata per pubblicare un oggetto FoodShoppingCart.

Kotlin


client.publishFoodShoppingCart(
            PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    FoodShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java


client.publishFoodShoppingCart(
            new PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    new FoodShoppingCart.Builder()
                        ...
                        .build())
                .build());

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

  • I dati di FoodShoppingCart 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.

publishFoodShoppingList

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.

publishReorderCluster

Questa API viene utilizzata per pubblicare un oggetto FoodReorderCluster.

Kotlin


client.publishReorderCluster(
            PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    FoodReorderCluster.Builder()
                        ...
                        .build())
                .build())

Java


client.publishReorderCluster(
            new PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    new FoodReorderCluster.Builder()
                        ...
                        .build())
                .build());

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

  • I dati di FoodReorderCluster 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 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.

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.

deleteFoodShoppingCartCluster

Questa API viene utilizzata per eliminare i contenuti del cluster di carrelli degli acquisti di alimenti.

Kotlin


client.deleteFoodShoppingCartCluster()

Java


client.deleteFoodShoppingCartCluster();

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

deleteFoodShoppingListCluster

Questa API viene utilizzata per eliminare i contenuti del cluster di liste della spesa di cibo.

Kotlin


client.deleteFoodShoppingListCluster()

Java


client.deleteFoodShoppingListCluster();

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

deleteReorderCluster

Questa API viene utilizzata per eliminare i contenuti di FoodRiordinaCluster.

Kotlin


client.deleteReorderCluster()

Java


client.deleteReorderCluster();

Quando il servizio riceve la richiesta, rimuove i dati esistenti dal cluster Riordina. 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.

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

// Trigger shopping list cluster publish when PUBLISH_FOOD_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.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));

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

// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.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.food.PUBLISH_FOOD_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER" />
      </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.food.PUBLISH_FOOD_SHOPPING_CART È consigliabile avviare una chiamata publishFoodShoppingCart quando ricevi questo intent.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST È consigliabile avviare una chiamata publishFoodShoppingList quando ricevi questo intent.
  • com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER Ti consigliamo di avviare una chiamata publishReorderCluster 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 engagement-developers@google.com 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 Engage-developers@google.com 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 Consiglio, In primo piano, Carrello degli acquisti, Lista della spesa e Riordina verranno pubblicati e saranno visibili agli utenti.