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 consente una nuova esperienza immersiva per la scoperta e il consumo di contenuti delle app personalizzati. Questa esperienza a schermo intero offre agli sviluppatori partner l'opportunità di mostrare i propri contenuti avanzati migliori in un canale dedicato al di fuori della loro app.

Questa guida contiene istruzioni per gli sviluppatori partner per integrare i propri contenuti relativi al cibo, utilizzando l'SDK Engage per compilare sia questa nuova area della piattaforma sia le piattaforme Google esistenti.

Dettaglio dell'integrazione

Terminologia

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

  • I cluster di consigli mostrano suggerimenti personalizzati relativi al cibo di un singolo sviluppatore partner. Questi consigli possono essere personalizzati in base all'utente o essere generici (ad es. novità in saldo). Utilizzali per mostrare ricette, negozi, piatti, generi alimentari e così via, come meglio credi.

    • Un cluster di consigli può essere composto da schede ProductEntity, StoreEntity o RecipeEntity, ma non da una combinazione di diversi tipi di entità.
    Figura : "ProductEntity", "StoreEntity" e "RecipeEntity". (*UI solo a scopo illustrativo)
  • Il cluster In primo piano mostra una selezione di entità di più sviluppatori partner in un unico raggruppamento dell'interfaccia utente. Verrà visualizzato un singolo cluster in primo piano, che viene visualizzato nella parte superiore dell'interfaccia utente con un posizionamento prioritario sopra tutti i cluster di consigli. Ogni sviluppatore partner potrà trasmettere fino a 10 entità nel cluster In primo piano.

    Figura : cluster in primo piano con l'entità "RecipeEntity". (*UI solo a scopo illustrativo)
  • Il cluster Carrello della spesa mostra un'anteprima dei carrelli della spesa di più sviluppatori partner in un unico raggruppamento dell'interfaccia utente, invitando gli utenti a completare i carrelli in sospeso. Esiste un singolo cluster di carrelli della spesa per alimenti.

    • Il cluster del carrello degli acquisti di generi alimentari deve mostrare il numero totale di articoli nel carrello e può includere anche immagini di X articoli nel carrello dell'utente.

      Figura: cluster di carrelli degli acquisti di prodotti alimentari di un singolo partner. (*Interfaccia utente solo a scopo illustrativo)
  • Il cluster Elenco della spesa mostra un'anteprima degli elenchi della spesa di più sviluppatori partner in un unico raggruppamento dell'interfaccia utente, invitando gli utenti a tornare all'app corrispondente per aggiornare e completare i loro elenchi. Esiste un singolo cluster di liste della spesa per alimenti.

    Figura: cluster di liste della spesa di un singolo partner. (*UI solo a scopo illustrativo)
  • Il cluster Riordina mostra un'anteprima degli ordini precedenti di più sviluppatori partner in un raggruppamento dell'interfaccia utente, invitando gli utenti a riordinare. Esiste un unico cluster di riordino.

    • Il cluster di riordino deve mostrare il conteggio totale degli articoli 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.
    Figura: cluster di riordino dei prodotti alimentari di un singolo partner. (*UI solo a scopo illustrativo)

Preparazione

Livello API minimo: 19

Aggiungi la raccolta com.google.android.engage:engage-core alla tua app:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

Riepilogo

Il design si basa su un'implementazione di un servizio vincolato.

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

Tipo di cluster Limiti del cluster Limiti massimi di entità in un cluster
Cluster di consigli Al massimo 5 Massimo 25 (ProductEntity, RecipeEntity o StoreEntity)
Cluster in primo piano Al massimo 1 Al massimo 10 (ProductEntity, RecipeEntity o StoreEntity)
Cluster di carrelli degli acquisti di cibo Al massimo 1 Al massimo 1 ShoppingCartEntity
Cluster di liste della spesa per alimenti Al massimo 1 Al massimo 1 ShoppingListEntity
Food Reorder Cluster Al massimo 1 Al massimo 1 ReorderEntity

Passaggio 1: fornisci i dati delle entità

L'SDK ha definito entità diverse per rappresentare ogni tipo di elemento. Supportiamo le seguenti entità per la categoria Cibo:

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

I grafici riportati di seguito illustrano gli attributi e i requisiti disponibili 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.

Figura : Attributi di ProductEntity

Attributo Requisito Descrizione Formato
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta le specifiche per le immagini.
URI azione Obbligatorio

Il link diretto alla pagina dell'app che mostra i dettagli del prodotto.

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

URI
Titolo Facoltativo Il nome del prodotto.

Testo libero

Dimensioni del testo consigliate: meno di 90 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati dei puntini di sospensione)

Prezzo - attuale Obbligatorio condizionalmente

Il prezzo corrente del prodotto.

Deve essere fornito se viene fornito il prezzo barrato.

Testo libero
Prezzo - barrato Facoltativo Il prezzo originale dell'entità, barrato nell'UI. Testo libero
Callout Facoltativo Callout per mettere in evidenza una promozione, un evento o un aggiornamento del prodotto, se disponibile.

Testo libero

Dimensioni del testo consigliate: meno di 45 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati puntini di sospensione)

Clausole del callout Facoltativo Testo delle clausole per il callout.

Testo libero

Dimensioni del testo consigliate: meno di 45 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati puntini di sospensione)

Valutazione (facoltativa) - Nota: tutte le valutazioni vengono visualizzate utilizzando il nostro sistema di valutazione a stelle standard.
Valutazione - Valore massimo Facoltativo

Il valore massimo della scala di valutazione.

Deve essere fornito se viene fornito anche il valore corrente della valutazione.

Numero >= 0,0
Valutazione - Valore corrente Facoltativo

Il valore attuale della scala di valutazione.

Deve essere fornito se viene fornito anche il valore massimo della valutazione.

Numero >= 0,0
Valutazione - Conteggio Facoltativo

Il numero di valutazioni del prodotto.

Nota:specifica questo campo se la tua app controlla il modo in cui il conteggio viene mostrato agli utenti. Utilizza una stringa concisa. Ad esempio, se il conteggio è 1.000.000, valuta la possibilità di utilizzare un'abbreviazione come 1M in modo che il conteggio non venga troncato su dimensioni di visualizzazione più piccole.

Stringa
Valutazione - Valore conteggio Facoltativo

Il numero di valutazioni del prodotto.

Nota: fornisci questo campo se non gestisci personalmente la logica di visualizzazione dell'abbreviazione. Se sono presenti sia Conteggio sia Valore conteggio, viene visualizzato Conteggio.

Lungo
DisplayTimeWindow (facoltativo) - Imposta una finestra temporale per la visualizzazione di contenuti sulla piattaforma
Timestamp inizio Facoltativo

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

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

Timestamp epoch in millisecondi
Timestamp di fine Facoltativo

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

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

Timestamp epoch in millisecondi

StoreEntity

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

Figura : Attributi di StoreEntity

Attributo Requisito Descrizione Formato
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta le specifiche per le immagini.
URI azione Obbligatorio

Il link diretto alla pagina dell'app che mostra i dettagli del negozio.

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

URI
Titolo Facoltativo Il nome del negozio.

Testo libero

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

Posizione Facoltativo La posizione del negozio.

Testo libero

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

Callout Facoltativo Callout per mettere in evidenza una promozione, un evento o un aggiornamento per il negozio, se disponibile.

Testo libero

Dimensioni del testo consigliate: meno di 45 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati puntini di sospensione)

Clausole del callout Facoltativo Testo delle clausole per il callout.

Testo libero

Dimensioni del testo consigliate: meno di 45 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati puntini di sospensione)

Descrizione Facoltativo Una descrizione del negozio.

Testo libero

Dimensioni del testo consigliate: meno di 90 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati puntini di sospensione)

Categoria Facoltativo

Categoria di un negozio, nel contesto dei locali per la ristorazione, può essere la cucina come "francese", "nuova americana", "ramen", "alta cucina".

Testo libero

Dimensioni del testo consigliate: meno di 45 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati puntini di sospensione)

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

Il valore massimo della scala di valutazione.

Deve essere fornito se viene fornito anche il valore corrente della valutazione.

Numero >= 0,0
Valutazione - Valore corrente Facoltativo

Il valore attuale della scala di valutazione.

Deve essere fornito se viene fornito anche il valore massimo della valutazione.

Numero >= 0,0
Valutazione - Conteggio Facoltativo

Il numero di valutazioni del negozio.

Nota:fornisci questo campo se la tua app vuole controllare la modalità di visualizzazione per gli utenti. Fornisci la stringa concisa che può essere mostrata all'utente. Ad esempio, se il conteggio è 1.000.000, valuta la possibilità di utilizzare abbreviazioni come 1M, in modo che non venga troncato su dimensioni di visualizzazione più piccole.

Stringa
Valutazione - Valore conteggio Facoltativo

Il numero di valutazioni del negozio.

Nota:fornisci questo campo se non vuoi gestire autonomamente la logica di visualizzazione dell'abbreviazione. Se sono presenti sia Conteggio sia Valore conteggi utilizzeremo il Conteggio per la visualizzazione agli utenti

Lungo

RecipeEntity

L'oggetto RecipeEntity rappresenta un elemento della ricetta che gli sviluppatori partner vogliono pubblicare.

Figura : Attributi di RecipeEntity

Attributo Requisito Descrizione Formato
Immagini dei poster Obbligatorio Devi specificare almeno un'immagine. Per indicazioni, consulta le specifiche per le immagini.
URI azione Obbligatorio

Il link diretto alla pagina dell'app che mostra i dettagli della ricetta.

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

URI
Titolo Facoltativo Il nome della ricetta.

Testo libero

Dimensioni del testo consigliate: meno di 45 caratteri (il testo troppo lungo potrebbe mostrare 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 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 puntini di sospensione)

Callout Facoltativo Callout per mettere in evidenza una promozione, un evento o un aggiornamento per la ricetta, se disponibile.

Testo libero

Dimensioni del testo consigliate: meno di 45 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati puntini di sospensione)

Categoria Facoltativo La categoria della ricetta.

Testo libero

Dimensioni del testo consigliate: meno di 45 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati puntini di sospensione)

Descrizione Facoltativo Una descrizione della ricetta.

Testo libero

Dimensioni del testo consigliate: meno di 90 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati puntini di sospensione)

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

Il valore massimo della scala di valutazione.

Deve essere fornito se viene fornito anche il valore corrente della valutazione.

Numero >= 0,0
Valutazione - Valore corrente Facoltativo

Il valore attuale della scala di valutazione.

Deve essere fornito se viene fornito anche il valore massimo della valutazione.

Numero >= 0,0
Valutazione - Conteggio Facoltativo

Il numero di valutazioni della ricetta.

Nota:fornisci questo campo se la tua app vuole controllare la modalità di visualizzazione per gli utenti. Fornisci la stringa concisa che può essere mostrata all'utente. Ad esempio, se il conteggio è 1.000.000, valuta la possibilità di utilizzare abbreviazioni come 1M, in modo che non venga troncato su dimensioni di visualizzazione più piccole.

Stringa
Valutazione - Valore conteggio Facoltativo

Il numero di valutazioni della ricetta.

Nota:fornisci questo campo se non vuoi gestire autonomamente la logica di visualizzazione dell'abbreviazione. Se sono presenti sia Conteggio sia Valore conteggio, utilizzeremo il Conteggio per la visualizzazione agli utenti

Lungo

FoodShoppingCart

Figura: attributi del cluster del carrello degli acquisti di prodotti alimentari.

Attributo Requisito Descrizione Formato
URI azione Obbligatorio

Il link diretto al carrello degli acquisti nell'app del partner.

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

URI
Numero di elementi Obbligatorio

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 un titolo, Il tuo carrello è il valore predefinito.

Testo libero

Dimensioni del testo consigliate: meno di 25 caratteri. Il testo troppo lungo potrebbe mostrare puntini di sospensione.

Testo dell'azione Facoltativo

Il testo dell'invito all'azione del pulsante nel carrello degli acquisti (ad es. Il tuo carrello).

Se lo sviluppatore non fornisce alcun testo dell'azione, Visualizza carrello è il valore predefinito.

Questo attributo è supportato dalla versione 1.1.0 in poi.

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 indicazioni, consulta le specifiche per le immagini.
Etichette elemento Facoltativo

L'elenco delle etichette per gli 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

Dimensioni del testo consigliate: meno di 20 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati dei puntini di sospensione)

DisplayTimeWindow (facoltativo) - Imposta una finestra temporale per la visualizzazione di contenuti sulla piattaforma
Timestamp inizio Facoltativo

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

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

Timestamp epoch in millisecondi
Timestamp di fine Facoltativo

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

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

Timestamp epoch in millisecondi

FoodShoppingList

Figura: cluster di liste della spesa per alimenti.

Attributo Requisito Descrizione Formato
URI azione Obbligatorio

Il link diretto alla lista della spesa nell'app del partner.

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

URI
Numero di elementi Obbligatorio Il numero di articoli nella lista della spesa. Numero intero >= 1
Titolo Facoltativo

Il titolo dell'elenco (ad esempio La tua lista della spesa).

Se lo sviluppatore non fornisce un titolo, Lista della spesa è il valore predefinito.

Testo libero

Dimensioni del testo consigliate: meno di 25 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati i puntini di sospensione)

Etichette elemento Obbligatorio

L'elenco delle etichette per gli articoli presenti nella lista della spesa.

Deve essere fornita almeno un'etichetta e possono essere fornite 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

Dimensioni del testo consigliate: meno di 20 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati dei puntini di sospensione)

FoodReorderCluster

Figura: cluster di riordino dei prodotti alimentari.

Attributo Requisito Descrizione Formato
URI azione Obbligatorio

Il link diretto per ordinare nuovamente nell'app del partner.

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

URI
Testo dell'azione Facoltativo

Il testo di invito all'azione del pulsante su Riordina (ad es. Ordina di nuovo).

Se lo sviluppatore non fornisce alcun testo dell'azione, Riordina è l'impostazione predefinita.

Questo attributo è supportato dalla versione 1.1.0 in poi.

Stringa
Numero di elementi Obbligatorio

Il numero di articoli (non solo il numero di prodotti) nell'ordine precedente.

Ad esempio: se nell'ordine precedente c'erano 3 caffè piccoli e 1 croissant, questo numero deve essere 4.

Numero intero >= 1
Titolo Obbligatorio Il titolo dell'articolo da ordinare di nuovo.

Testo libero

Dimensioni del testo consigliate: meno di 40 caratteri (se il testo è troppo lungo, potrebbero essere visualizzati i puntini di sospensione)

Etichette elemento

Facoltativo

(se non fornite, devono essere fornite immagini poster)

L'elenco delle etichette degli articoli 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: meno di 20 caratteri (il testo troppo lungo potrebbe mostrare puntini di sospensione)

Immagini dei poster

Facoltativo

(se non specificato, devono essere fornite 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 indicazioni, consulta le specifiche per le immagini.

Specifiche per le immagini

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

Proporzioni Numero minimo di pixel Risoluzione consigliata in pixel

Quadrato (1 x 1)

Preferito

300x300 1200x1200
Orizzontale (1,91 x 1) 600x314 1200x628
Ritratto (4 x 5) 480x600 960x1200

Formati file

PNG, JPG, GIF statico, WebP

Dimensioni massime del file

5120 kB

Consigli aggiuntivi

  • Area di sicurezza dell'immagine:inserisci i contenuti importanti al centro dell'immagine in modo da occuparne l'80%.
  • Utilizza uno sfondo trasparente in modo che l'immagine possa essere visualizzata correttamente nelle impostazioni dei temi scuro e chiaro.

Passaggio 2: fornisci i dati del cluster

Ti consigliamo di eseguire il job di pubblicazione dei contenuti in background (ad esempio utilizzando WorkManager) e di pianificarlo su base regolare o in base a un evento (ad esempio ogni volta che l'utente apre l'app o quando l'utente ha appena aggiunto un articolo al carrello).

AppEngageFoodClient è responsabile della pubblicazione dei cluster di alimenti.

Esistono le seguenti 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 Obbligatorio Un elenco di entità che compongono i consigli per questo cluster di consigli. Le entità in un singolo cluster devono essere dello stesso tipo.
Titolo Obbligatorio

Il titolo del cluster di consigli (ad es. Grandi risparmi sul menu del giorno del Ringraziamento).

Dimensioni del testo consigliate: meno di 25 caratteri. Il testo troppo lungo potrebbe mostrare puntini di sospensione.

Sottotitolo Facoltativo Il sottotitolo del cluster di consigli.
URI azione Facoltativo

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

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

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, vengono eseguite le seguenti azioni all'interno di una transazione:

  • Tutti i dati esistenti dei cluster di consigli vengono rimossi.
  • I dati della richiesta vengono analizzati e archiviati in nuovi cluster di consigli.

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

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, vengono eseguite le seguenti azioni all'interno di una transazione:

  • I dati FeaturedCluster esistenti del partner sviluppatore vengono rimossi.
  • I dati della richiesta vengono analizzati e archiviati nel cluster in primo piano aggiornato.

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

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, vengono eseguite le seguenti azioni all'interno di una transazione:

  • I dati FoodShoppingCart esistenti del partner sviluppatore vengono rimossi.
  • I dati della richiesta vengono analizzati e archiviati nel cluster del carrello aggiornato.

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

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, vengono eseguite le seguenti azioni all'interno di una transazione:

  • I dati FoodShoppingList esistenti del partner sviluppatore vengono rimossi.
  • I dati della richiesta vengono analizzati e archiviati nel cluster aggiornato della lista della spesa.

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

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, vengono eseguite le seguenti azioni all'interno di una transazione:

  • I dati FoodReorderCluster esistenti del partner sviluppatore vengono rimossi.
  • I dati della richiesta vengono analizzati e archiviati nel cluster di ordinamento aggiornato.

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

publishUserAccountManagementRequest

Questa API viene utilizzata per pubblicare una scheda Accedi . L'azione di accesso indirizza gli utenti alla pagina di accesso dell'app in modo che l'app possa pubblicare contenuti (o fornire contenuti più personalizzati).

I seguenti metadati fanno parte della scheda Accedi:

Attributo Requisito Descrizione
URI azione Obbligatorio Link diretto all'azione (ad es. alla pagina di accesso all'app)
Immagine (Facoltativo) Se non viene fornito, deve essere fornito il titolo

Immagine mostrata sulla scheda

Immagini con proporzioni 16 x 9 e una risoluzione di 1264 x 712

Titolo Facoltativo: se non viene fornito, deve essere fornita l'immagine Nome sulla carta
Testo dell'azione Facoltativo Testo visualizzato nell'invito all'azione (ad es. Accedi)
Sottotitolo Facoltativo Sottotitolo facoltativo nella scheda

Kotlin

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

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

Java

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

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

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

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

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

updatePublishStatus

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

  • Fornire lo stato in tutti gli scenari, anche quando i contenuti sono pubblicati (STATUS == PUBLISHED), è fondamentale per compilare le dashboard che utilizzano questo stato esplicito per trasmettere l'integrità e altre metriche dell'integrazione.
  • Se non vengono pubblicati contenuti, ma lo stato dell'integrazione non è in errore (STATUS == NOT_PUBLISHED), Google può evitare di attivare avvisi nelle dashboard relative alla salute dell'app. Conferma che i contenuti non vengono pubblicati a causa di una situazione prevedibile dal punto di vista del fornitore.
  • Aiuta gli sviluppatori a fornire informazioni su quando i dati vengono pubblicati o meno.
  • Google potrebbe utilizzare i codici di stato per indurre l'utente a eseguire determinate azioni nell'app in modo da poter visualizzare i contenuti dell'app o superarli.

L'elenco dei codici di stato di pubblicazione idonei è il seguente :

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

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

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

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

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

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

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

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

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

Se i contenuti non vengono pubblicati perché un utente non ha eseguito l'accesso, Google consiglia di pubblicare la scheda di accesso. Se per qualsiasi motivo i fornitori non sono in grado di pubblicare la scheda di accesso, consigliamo di chiamare l'API updatePublishStatus con il codice 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 gruppi 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.

deleteFoodShoppingCartCluster

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

Kotlin

client.deleteFoodShoppingCartCluster()

Java

client.deleteFoodShoppingCartCluster();

Quando il servizio riceve la richiesta, rimuove i dati esistenti dal cluster del carrello degli acquisti di generi alimentari. 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 della lista della spesa per alimenti.

Kotlin

client.deleteFoodShoppingListCluster()

Java

client.deleteFoodShoppingListCluster();

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

Kotlin

client.deleteReorderCluster()

Java

client.deleteReorderCluster();

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

deleteUserManagementCluster

Questa API viene utilizzata per eliminare i contenuti del cluster UserAccountManagement.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

deleteClusters

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

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      ...
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                ...
                .build());

Quando il servizio riceve la richiesta, rimuove i dati esistenti da tutti i cluster corrispondenti ai tipi di cluster specificati. I client possono scegliere di passare uno o più tipi di cluster. In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene mantenuto.

Gestione degli errori

Ti consigliamo vivamente di ascoltare il risultato dell'attività dalle API di pubblicazione in modo da poter intraprendere un'azione di follow-up per recuperare e inviare nuovamente un'attività riuscita.

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

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

Codice di errore Nome dell'errore Nota
1 SERVICE_NOT_FOUND Il servizio non è disponibile sul dispositivo specificato.
2 SERVICE_NOT_AVAILABLE Il servizio è disponibile sul dispositivo specificato, ma non al momento della chiamata (ad esempio, è disabilitato esplicitamente).
3 SERVICE_CALL_EXECUTION_FAILURE L'esecuzione dell'attività non è riuscita a causa di problemi di threading. In questo caso, è possibile eseguire nuovamente la richiesta.
4 SERVICE_CALL_PERMISSION_DENIED Il chiamante non è autorizzato a effettuare la chiamata di servizio.
5 SERVICE_CALL_INVALID_ARGUMENT La richiesta contiene dati non validi (ad esempio, più del numero di cluster consentito).
6 SERVICE_CALL_INTERNAL Si è verificato un errore lato servizio.
7 SERVICE_CALL_RESOURCE_EXHAUSTED La chiamata al servizio viene effettuata troppo di frequente.

Passaggio 3: gestisci gli intent di trasmissione

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

Lo scopo degli intent di trasmissione è principalmente la riattivazione dell'app e l'applicazione forzata della sincronizzazione dei dati. Gli intent di trasmissione non sono progettati per essere inviati molto di frequente. Viene attivata solo quando il servizio Engage determina che i contenuti potrebbero essere obsoleti (ad esempio, risalenti a una settimana prima). In questo modo, l'utente può avere maggiore fiducia di poter usufruire di contenuti aggiornati, anche se l'applicazione non è stata eseguita per un lungo periodo di tempo.

BroadcastReceiver deve essere configurato nei seguenti due modi:

  • Registra dinamicamente un'istanza della classe BroadcastReceiver utilizzando Context.registerReceiver(). In questo modo, viene attivata la comunicazione da applicazioni che sono ancora attive 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 AndroidManifest.xml file. In questo modo, l'applicazione può ricevere intent di trasmissione quando non è in esecuzione e pubblicare i contenuti.
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android: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 invierà i seguenti intent:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION È consigliabile avviare una chiamata publishRecommendationClusters quando si riceve questa intenzione.
  • com.google.android.engage.action.PUBLISH_FEATURED È consigliabile avviare una chiamata publishFeaturedCluster quando si riceve questo intento.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART È consigliabile avviare una chiamata publishFoodShoppingCart quando si riceve questo intento.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST È consigliabile avviare una chiamata publishFoodShoppingList quando si riceve questo intento.
  • com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER È consigliabile avviare una chiamata publishReorderCluster quando si riceve questo intent.

Flusso di lavoro di integrazione

Per una guida passo passo sulla verifica dell'integrazione al termine, consulta Flusso di lavoro di integrazione degli sviluppatori di Engage.

Domande frequenti

Per le 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, svolgi i seguenti passaggi:

  • Invia un'email all'indirizzo engage-developers@google.com e allega il tuo APK integrato pronto per i test di Google.
  • Google eseguirà una verifica e una revisione interna per assicurarsi che l'integrazione funzioni come previsto. Se sono necessarie modifiche, Google ti contatterà fornendoti tutti i dettagli necessari.
  • Al termine del test, se non sono necessarie modifiche, Google ti contatterà per informarti che puoi iniziare a pubblicare l'APK aggiornato e integrato sul Play Store.
  • Dopo che Google avrà confermato che il tuo APK aggiornato è stato pubblicato sul Play Store, i cluster Consiglio, In evidenza, Carrello degli acquisti, Elenco della spesa e Riordina verranno pubblicati e visibili agli utenti.