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

Aumenta il coinvolgimento con l'app raggiungendo i tuoi utenti ovunque si trovino. Integra l'SDK Engage per fornire suggerimenti personalizzati e contenuti in continuità direttamente agli utenti su più piattaforme on-device, come Raccolte, Entertainment Space e il Play Store. L'integrazione aggiunge meno di 50 KB (compressi) all'APK medio e richiede circa una settimana di lavoro per gli sviluppatori della maggior parte delle app. Scopri di più sul nostro sito aziendale.

Questa guida contiene istruzioni per gli sviluppatori partner su come pubblicare contenuti dei social media sulle piattaforme di contenuti di Engage.

Supporto delle categorie e piattaforme

L'idoneità alla piattaforma dell'SDK Engage si basa sulla categoria di contenuti della tua app. Utilizza la tabella seguente per determinare la tua idoneità per piattaforme specifiche:

Stato	Categoria di contenuti o caso d'uso	Piattaforme supportate
Supportato (Idoneo su tutte le piattaforme)	Social network Immagine / meme Video clip / video nel formato breve Incontri di persona Archiviazione di foto nel cloud	Raccolte Scheda App Play Store Scheda Tu del Play Store Pagina della scheda del Play Store
Non supportato	Video chat live Messaggistica immediata, condivisione della presenza online o dati in tempo reale Condivisione file e downloader Incontri Generatori di avatar

Competenze Android

Visualizza su GitHub

Integra l'SDK Engage

Utilizza la competenza Android dell'SDK Engage per integrare, eseguire il debug e risolvere i problemi di implementazione.

Per installare lo skill dalla CLI Android, esegui:

android skills add engage-sdk-integration

Dettaglio dell'integrazione

La sezione seguente illustra i dettagli dell'integrazione.

Terminologia

I cluster di consigli mostrano suggerimenti personalizzati di un singolo partner sviluppatore.

I suggerimenti hanno la seguente struttura:

Cluster di consigli: visualizzazione dell'interfaccia utente che contiene un gruppo di consigli dello stesso partner sviluppatore.

Ogni cluster di suggerimenti è costituito da uno dei seguenti due tipi di entità :

• PortraitMediaEntity
• SocialPostEntity

PortraitMediaEntity deve contenere un'immagine verticale per il post. I metadati relativi al profilo e all'interazione sono facoltativi.

• Pubblica

  • Immagine in modalità Ritratto e timestamp oppure
  • Immagine in modalità Ritratto + contenuti di testo e timestamp

• Profilo

  • Avatar, nome o handle, immagine aggiuntiva

• Interazioni

  • Solo conteggio ed etichettatura oppure
  • Conteggio e visualizzazione (icona)

SocialPostEntity contiene i metadati relativi a profilo, post e interazione.

• Profilo

  • Avatar, nome o handle, testo aggiuntivo, immagine aggiuntiva

• Pubblica

  • Testo e timestamp oppure
  • Rich media (immagine o URL rich) e timestamp oppure
  • Testo e rich media (immagine o URL rich) e timestamp oppure
  • Anteprima del video (miniatura e durata) e timestamp

• Interazioni

  • Solo conteggio ed etichettatura oppure
  • Conteggio e visualizzazione (icona)

Preparazione

Livello API minimo: 19

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

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.6.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 i diversi tipi di cluster:

Tipo di cluster	Limiti dei cluster	Limiti minimi delle entità in un cluster	Limiti massimi di entità in un cluster
Cluster di suggerimenti	Al massimo 7	Almeno 1 (PortraitMediaEntity o SocialPostEntity)	Al massimo 50 (PortraitMediaEntity o SocialPostEntity)

Passaggio 1: fornisci i dati della persona giuridica

L'SDK ha definito entità diverse per rappresentare ogni tipo di articolo. L'SDK supporta le seguenti entità per la categoria Social:

1. PortraitMediaEntity
2. SocialPostEntity

I seguenti grafici illustrano gli attributi e i requisiti disponibili per ogni tipo.

PortraitMediaEntity

Attributo	Requisito	Descrizione	Formato
URI azione	Obbligatorio per tutte le piattaforme diverse da Google TV	Deep link all'entità nell'app del fornitore. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti	URI
PlatformSpecificPlayback	Obbligatorio per la piattaforma Google TV	Deep link all'entità nell'app del fornitore per piattaforme come Google TV e dispositivi mobili.	Elenco di oggetti PlatformSpecificPlayback
Motivo del consiglio	Facoltativo	La motivazione per cui i contenuti vengono consigliati all'utente.	Oggetto RecommendationReason
Riepilogo dei commenti	Facoltativo	Riepilogo dei commenti al post.	Stringa
Metadati relativi al post (obbligatorio)
Immagini	Obbligatorio	Le immagini devono avere proporzioni verticali. La UI potrebbe mostrare una sola immagine quando ne vengono fornite più di una. Tuttavia, l'UI potrebbe fornire un'indicazione visiva della presenza di altre immagini nell'app. Se il post è un video, il fornitore deve fornire una miniatura del video da mostrare come immagine.	Per indicazioni, consulta le specifiche per le immagini.
Contenuti testuali	Facoltativo	Il testo principale di un post, un aggiornamento e così via.	Stringa (massimo consigliato 140 caratteri)
Timestamp	Facoltativo	L'ora in cui è stato pubblicato il post.	Timestamp epoch in millisecondi
È un contenuto video	Facoltativo	Il post è un video?	boolean
Durata video	Facoltativo	La durata del video in millisecondi.	Lungo
(Facoltativo) Metadati relativi al profilo
Nome	Obbligatorio	Nome, ID o handle del profilo, ad esempio "Mario Rossi", "@TeamPixel"	Stringa(massimo 25 caratteri consigliati)
Avatar	Obbligatorio	Immagine del profilo o avatar dell'utente. Immagine quadrata 1:1	Per indicazioni, consulta le specifiche per le immagini.
Immagine aggiuntiva	Facoltativo	Badge del profilo, ad esempio il badge di verifica Immagine quadrata 1:1	Per indicazioni, consulta le specifiche per le immagini.
Metadati relativi alle interazioni (facoltativo)
Conteggio	Facoltativo	Indica il numero di interazioni, ad esempio "3,7 M". Nota: se vengono forniti sia Count che Count Value, verrà utilizzato Count. Nota:i partner devono utilizzare Count o CountWithOptionalLabel.	Stringa
CountWithOptionalLabel	Facoltativo	Indica il numero di interazioni con un'etichetta facoltativa, ad esempio "3,7 milioni di Mi piace". Nota: se vengono forniti sia CountWithOptionalLabel sia Count Value, verrà utilizzato uno dei due. Nota:i partner devono utilizzare Count o CountWithOptionalLabel.	Stringa
Valore conteggio	Facoltativo	Il numero di interazioni come valore. Nota:fornisci Count Value anziché Count se la tua app non gestisce la logica relativa alla modalità di ottimizzazione di un numero elevato per schermi di dimensioni diverse. Se vengono forniti sia Conteggio che Valore conteggio, viene utilizzato Conteggio.	Lungo
Etichetta	Facoltativo	Indica lo scopo dell'etichetta di interazione. Ad esempio, "Mi piace".	Stringa
Visivo	Facoltativo	Indica lo scopo dell'interazione. Ad esempio, un'immagine che mostra l'icona Mi piace, un'emoji. Puoi fornire più di un'immagine, anche se non tutte potrebbero essere visualizzate su tutti i fattori di forma. Nota:deve essere un'immagine quadrata 1:1	Per indicazioni, consulta le specifiche per le immagini.
DisplayTimeWindow (facoltativo): imposta un intervallo di tempo per la visualizzazione di un contenuto sulla piattaforma
Timestamp di inizio	Facoltativo	Il timestamp epoch dopo il quale i contenuti devono essere mostrati sulla piattaforma. Se non viene 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ù mostrati sulla piattaforma. Se non viene impostato, i contenuti sono idonei alla visualizzazione sulla piattaforma.	Timestamp epoch in millisecondi

SocialPostEntity

Attributo	Requisito	Descrizione	Formato
URI azione	Obbligatorio	Deep link all'entità nell'app del fornitore. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti	URI
URI PlatformSpecificPlayback	Obbligatorio per la piattaforma Google TV	Deep link all'entità nell'app del fornitore per piattaforme come Google TV e dispositivi mobili.	Elenco di oggetti PlatformSpecificPlayback
Motivo del consiglio	Facoltativo	La motivazione per cui i contenuti vengono consigliati all'utente.	Oggetto RecommendationReason
Riepilogo dei commenti	Facoltativo	Riepilogo dei commenti al post.	Stringa
Metadati relativi al post (obbligatorio) È obbligatorio almeno uno dei seguenti elementi: TextContent, Image o WebContent
Immagini	Facoltativo	Le immagini devono avere proporzioni verticali. La UI potrebbe mostrare una sola immagine quando ne vengono fornite più di una. Tuttavia, l'UI potrebbe fornire un'indicazione visiva della presenza di altre immagini nell'app. Se il post è un video, il fornitore deve fornire una miniatura del video da mostrare come immagine.	Per indicazioni, consulta le specifiche per le immagini.
Contenuti testuali	Facoltativo	Il testo principale di un post, un aggiornamento e così via.	Stringa (massimo consigliato 140 caratteri)
(Facoltativo) Contenuti video
Durata	Obbligatorio	La durata del video in millisecondi.	Lungo
Immagine	Obbligatorio	Immagine di anteprima dei contenuti video.	Per indicazioni, consulta le specifiche per le immagini.
Anteprima link (facoltativa)
Anteprima link - Titolo	Obbligatorio	Testo per indicare il titolo dei contenuti della pagina web	Stringa
Anteprima link - Nome host	Obbligatorio	Testo per indicare il proprietario della pagina web, ad esempio "ADDETTO AI LAVORI"	Stringa
Anteprima link - Immagine	Facoltativo	Immagine hero per i contenuti web	Per indicazioni, consulta le specifiche per le immagini.
Timestamp	Facoltativo	L'ora in cui è stato pubblicato il post.	Timestamp epoch in millisecondi
(Facoltativo) Metadati relativi al profilo
Nome	Obbligatorio	Nome, ID o handle del profilo, ad esempio "Mario Rossi", "@TeamPixel".	Stringa(massimo 25 caratteri consigliati)
Testo aggiuntivo	Facoltativo	Può essere utilizzato come ID profilo, handle o metadati aggiuntivi Ad esempio "@John-Doe", "5 milioni di follower", "Potrebbe piacerti", "In tendenza", "5 nuovi post"	Stringa(massimo 40 caratteri consigliati)
Avatar	Obbligatorio	Immagine del profilo o avatar dell'utente. Immagine quadrata 1:1	Per indicazioni, consulta le specifiche per le immagini.
Immagine aggiuntiva	Facoltativo	Badge del profilo, ad esempio il badge di verifica Immagine quadrata 1:1	Per indicazioni, consulta le specifiche per le immagini.
Metadati relativi alle interazioni (facoltativo)
Conteggio	Obbligatorio	Indica il numero di interazioni, ad esempio "3,7 M". Nota:i partner devono utilizzare Count o CountWithOptionalLabel.	Stringa
CountWithOptionalLabel	Obbligatorio	Indica il numero di interazioni con un'etichetta facoltativa, ad esempio "3,7 milioni di Mi piace". Nota:i partner devono utilizzare Count o CountWithOptionalLabel.	Stringa
Etichetta	Facoltativo Se non viene fornito, è necessario fornire Visual.	Indica lo scopo dell'interazione. Ad esempio, "Mi piace".	Stringa (massimo 20 caratteri consigliati per la combinazione di conteggio ed etichetta)
Visivo	Facoltativo Se non viene fornito, deve essere fornita l'etichetta.	Indica lo scopo dell'interazione. Ad esempio, un'immagine che mostra l'icona Mi piace, un'emoji. Puoi fornire più di un'immagine, anche se non tutte potrebbero essere mostrate su tutti i fattori di forma. Immagine quadrata 1:1	Per indicazioni, consulta le specifiche per le immagini.
DisplayTimeWindow (facoltativo): imposta un intervallo di tempo per la visualizzazione di un contenuto sulla piattaforma
Timestamp di inizio	Facoltativo	Il timestamp epoch dopo il quale i contenuti devono essere mostrati sulla piattaforma. Se non viene 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ù mostrati sulla piattaforma. Se non viene impostato, i contenuti sono idonei alla visualizzazione sulla piattaforma.	Timestamp epoch in millisecondi

Specifiche per le immagini

Le immagini devono essere ospitate su CDN pubbliche in modo che Google possa accedervi.

Formati file

PNG, JPG, GIF statico, WebP

Dimensioni massime del file

5120 kB

Altri consigli

• Area di sicurezza per l'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 regolarmente o in base a un evento (ad esempio, ogni volta che l'utente apre l'app o quando l'utente ha appena seguito un nuovo account).

AppEngageSocialClient è responsabile della pubblicazione dei cluster social.

Esistono le seguenti API per pubblicare i cluster nel client:

• isServiceAvailable
• publishRecommendationClusters
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• 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.

Per l'SDK Engage v1.6.0 e versioni successive (consigliato)

Competenze Android

Visualizza su GitHub

Integrazione dell'SDK Engage

Per installare lo skill dalla CLI Android, esegui:

android skills add engage-sdk-integration

Se il tuo team utilizza strumenti di programmazione AI (come Gemini in Android Studio), puoi automatizzare questa migrazione chiedendo all'assistente AI:

Use the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.

Puoi verificare la disponibilità del servizio per ogni tipo di cluster che intendi pubblicare. L'API isServiceAvailable accetta un oggetto di richiesta, ServiceAvailabilityRequest, che contiene i tipi di cluster per i quali deve essere verificata la disponibilità del servizio. Puoi trovare i valori enum ClusterType richiesti per ServiceAvailabilityRequest nella tabella seguente.

Tipo di cluster	Costante del tipo di cluster	Valore intero
Sconosciuto	TYPE_UNKNOWN	0
Cluster di suggerimenti	TYPE_RECOMMENDATION	1
Cluster in primo piano	TYPE_FEATURED	2
Cluster di continuazione	TYPE_CONTINUATION	3
Cluster di gestione utenti	TYPE_ENGAGEMENT	8
Cluster di sottoscrizione	TYPE_SUBSCRIPTION	12

Kotlin

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

Java

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
});

Funzionalità di disponibilità del servizio condizionale

Alcune app integrate richiedono una configurazione speciale che attiva e disattiva il servizio Engage in modo intermittente per ridurre i costi di pubblicazione. Tuttavia, questa strategia di importazione di contenuti intermittente influisce negativamente sull'esperienza utente: i contenuti obsoleti non verranno presentati e alcune piattaforme non verranno pubblicate.

A partire dalla versione 1.6.0, l'SDK Engage consente di verificare la disponibilità di tipi di cluster specifici. Se ti interessa attivare questa funzionalità per qualsiasi tipo di cluster, contatta [e-mail].

Per le versioni dell'SDK precedenti alla 1.6.0 (ritirate)

Kotlin

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

Java

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

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

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 SocialPostEntity o PortraitMediaEntity	Obbligatorio	Un elenco di entità che costituiscono i suggerimenti per questo gruppo di suggerimenti. Le entità in un singolo cluster devono essere dello stesso tipo.
Titolo	Obbligatorio	Il titolo del cluster di consigli (ad esempio, Novità dei tuoi amici). Dimensioni del testo consigliate: meno di 25 caratteri (il testo troppo lungo potrebbe mostrare i puntini di sospensione)
Sottotitolo	Facoltativo	Il sottotitolo del gruppo di suggerimenti.
URI azione	Facoltativo	Il deep link alla pagina nell'app partner in cui gli utenti possono visualizzare l'elenco completo dei consigli. Nota: puoi utilizzare i deep link per l'attribuzione. Consulta queste domande frequenti

Importante: le API di pubblicazione sono API di upsert, ovvero sostituiscono i contenuti esistenti. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, in quanto le API di pubblicazione lo fanno intrinsecamente.

Importante: per le app social, è fondamentale aggiornare i consigli dopo ogni utilizzo dell'app. Gli utenti delle app social sono più interessati ai consigli più recenti e, idealmente, vorrebbero vedere un post al massimo una volta.

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build());

Quando il servizio riceve la richiesta, vengono eseguite le seguenti azioni all'interno 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 lo stato esistente viene mantenuto.

publishUserAccountManagementRequest

Questa API viene utilizzata per pubblicare una tessera di accesso . 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	Deep link all'azione (ad es. rimanda alla pagina di accesso all'app)
Immagine	Facoltativo. Se non viene fornito, è necessario fornire il titolo	Immagine mostrata sulla scheda Immagini con proporzioni 16:9 e risoluzione di 1264 x 712
Titolo	Facoltativo. Se non viene fornito, è necessario fornire l'immagine	Titolo sulla scheda
Testo di azione	Facoltativo	Testo mostrato nella CTA (ad es. Accedi)
Sottotitolo	Facoltativo	Sottotitolo facoltativo sulla scheda

Importante: le API di pubblicazione sono API di upsert, ovvero sostituiscono i contenuti esistenti. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, in quanto le API di pubblicazione lo fanno intrinsecamente.

Kotlin

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

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

Java

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

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

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

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

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

updatePublishStatus

Se per qualsiasi motivo aziendale interno 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 sono pubblicati (STATUS == PUBLISHED), è fondamentale per compilare le dashboard che utilizzano questo stato esplicito per comunicare l'integrità e altre metriche della tua integrazione.
• Se non vengono pubblicati contenuti, ma lo stato dell'integrazione non è interrotto (STATUS == NOT_PUBLISHED), Google può evitare di attivare avvisi nelle dashboard di integrità dell'app. Conferma che i contenuti non vengono pubblicati a causa di una situazione prevista dal punto di vista del fornitore.
• Aiuta gli sviluppatori a fornire informazioni su quando i dati vengono pubblicati e quando no.
• Google potrebbe utilizzare i codici di stato per invitare l'utente a eseguire determinate azioni nell'app in modo che possa visualizzare i contenuti dell'app o superare il problema.

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

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

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

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

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

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

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

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

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

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

Se i contenuti non vengono pubblicati perché un utente non ha eseguito l'accesso, Google consiglia di pubblicare la scheda di accesso. Se per qualsiasi motivo i fornitori non sono in grado di pubblicare la scheda di accesso, 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());

deleteRecommendationsClusters

Questa API viene utilizzata per eliminare i contenuti dei cluster di suggerimenti.

Importante: le API di eliminazione devono essere chiamate solo quando non sono presenti contenuti da pubblicare. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta [e-mail] prima di utilizzare le API di eliminazione.

Kotlin

client.deleteRecommendationsClusters()

Java

client.deleteRecommendationsClusters();

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.

deleteUserManagementCluster

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

Importante: le API di eliminazione devono essere chiamate solo quando non sono presenti contenuti da pubblicare. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta [e-mail] prima di utilizzare le API di eliminazione.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

deleteClusters

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

Importante: le API di eliminazione devono essere chiamate solo quando non sono presenti contenuti da pubblicare. Non chiamare le API di eliminazione e pubblicazione successivamente per sostituire i contenuti, poiché le API di pubblicazione lo fanno intrinsecamente. Contatta [e-mail] prima di utilizzare le API di eliminazione.

Kotlin

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

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .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 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 è disponibile al momento della chiamata (ad esempio, è disattivato esplicitamente).
3	SERVICE_CALL_EXECUTION_FAILURE	L'esecuzione dell'attività non è riuscita a causa di problemi di threading. In questo caso, è possibile riprovare.
4	SERVICE_CALL_PERMISSION_DENIED	Il chiamante non è autorizzato a effettuare la chiamata di servizio.
5	SERVICE_CALL_INVALID_ARGUMENT	La richiesta contiene dati non validi (ad esempio, un numero di cluster superiore a quello consentito).
6	SERVICE_CALL_INTERNAL	Si è verificato un errore lato servizio.
7	SERVICE_CALL_RESOURCE_EXHAUSTED	La chiamata di servizio viene effettuata troppo di frequente.

Passaggio 3: gestisci gli intent di trasmissione

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

L'obiettivo degli intent di trasmissione è principalmente la riattivazione dell'app e la sincronizzazione forzata dei dati. Gli intent di trasmissione non sono progettati per essere inviati molto di frequente. Viene attivato solo quando il servizio Engage determina che i contenuti potrebbero essere obsoleti (ad esempio, risalenti a una settimana prima). In questo modo, è più probabile che l'utente possa usufruire di un'esperienza con 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, le applicazioni ancora attive in memoria possono comunicare.

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION
  // broadcast is received
}

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

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

Java

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);
}

• Dichiara staticamente un'implementazione con il tag <receiver> nel file AndroidManifest.xml. In questo modo, l'applicazione può ricevere intent di trasmissione quando non è in esecuzione e può anche pubblicare i contenuti.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
   </receiver>
</application>

I seguenti intent verranno inviati dal servizio:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION Ti consigliamo di avviare una chiamata publishRecommendationClusters quando ricevi questo intent.

Workflow di integrazione

Per una guida passo passo sulla verifica dell'integrazione una volta completata, consulta il flusso di lavoro di integrazione per gli sviluppatori di Engage.

Domande frequenti

Per le domande frequenti, consulta Domande frequenti sull'SDK Engage.

Contatto

Contatta [e-mail] in caso di domande durante il processo di integrazione. Il nostro team ti risponderà il prima possibile.

Passaggi successivi

Dopo aver completato questa integrazione, i passaggi successivi sono i seguenti:

• Invia un'email all'indirizzo [e-mail] e allega l'APK integrato pronto per essere testato da Google.
• Google esegue una verifica e dei controlli interni per assicurarsi che l'integrazione funzioni come previsto. Se sono necessarie modifiche, Google ti contatterà con tutti i dettagli necessari.
• Al termine dei test, se non sono necessarie modifiche, Google ti contatta per informarti che puoi iniziare a pubblicare l'APK aggiornato e integrato sul Play Store.
• Dopo che Google avrà confermato che l'APK aggiornato è stato pubblicato sul Play Store, i cluster di suggerimenti verranno pubblicati e saranno visibili agli utenti.