Linee guida sulla pubblicazione dei cluster di SDK Engage

Questa guida include una serie di linee guida per la pubblicazione di cluster che gli sviluppatori possono utilizzare durante l'integrazione con l'SDK Engage.

Cluster di suggerimenti

Titolo cluster

Ti consigliamo di fornire un titolo del cluster univoco e pertinente che offra agli utenti informazioni più dettagliate sui contenuti del cluster.

Di seguito sono riportati alcuni esempi di titoli di cluster efficaci in base ai contenuti:

  • Cluster correlati a Shopping
    • Offerte Lightning
    • Acquisti imperdibili settimanali
    • Prodotti correlati all'acquisto di Pixel Buds
    • Stivali da pioggia da donna
  • Gruppi di libri sulla salute
    • Salute, mente e corpo
    • Consigliati per te in Salute
    • Più venduti in fitness

Contenuti del cluster

Quando pubblicano cluster di suggerimenti, gli sviluppatori devono valutare se l'utente ha eseguito o meno l'accesso all'applicazione dello sviluppatore.

Quando l'utente ha eseguito l'accesso

Se l'utente ha eseguito l'accesso all'app per sviluppatori, ti consigliamo di pubblicare cluster di contenuti personalizzati o generati dagli utenti. Poiché i contenuti personalizzati e generati dagli utenti sono più pertinenti per l'utente, quest'ultimo è più motivato a visitare l'app per sviluppatori sulla piattaforma Google.

  • È possibile pubblicare consigli personalizzati.
    • Ecco alcuni esempi di consigli personalizzati:
      • Scelti in base alla cronologia delle visualizzazioni dell'utente.
      • Libri simili ai libri presenti nella cronologia di lettura dell'utente.
      • Brani degli artisti preferiti dell'utente.
  • Le raccolte di contenuti generati dagli utenti possono essere pubblicate.
    • Ecco alcuni esempi di raccolte di contenuti generati dagli utenti:
      • Lista di titoli dell'utente dall'app sviluppatore.
      • Un elenco di artisti preferiti dell'utente che ha segnalato autonomamente dall'app sviluppatore.
Tipo di consiglio Strategia di aggiornamento dei contenuti Linee guida relative all'aggiornamento dei contenuti
Consigli personalizzati

Indigente

Consigliamo di aggiornare i consigli una volta al giorno in modo che gli utenti possano vederne di nuovi ogni giorno.

 Poiché gli utenti non hanno un'idea precisa di quali saranno i contenuti dei suggerimenti, la strategia di aggiornamento dei contenuti può essere indulgente.
Raccolte di contenuti generati dagli utenti

Rigorosa

Ti consigliamo di aggiornare la raccolta di contenuti quando gli utenti escono dall'app per sviluppatori.

 È importante che questi contenuti siano sincronizzati con i dati visualizzati sulle piattaforme Google. Questo perché, a differenza dei consigli personalizzati, l'utente si aspetta un insieme esatto di contenuti. Qualsiasi ritardo significativo nella pubblicazione può confondere gli utenti. Pertanto, la strategia di aggiornamento dei contenuti deve essere rigorosa.

Se l'utente non ha eseguito l'accesso

Se un utente non ha eseguito l'accesso all'app per sviluppatori, consigliamo comunque di pubblicare i cluster, in modo che gli utenti siano incoraggiati a visitare l'app per sviluppatori dalla piattaforma Google.

  • I cluster di suggerimenti non personalizzati devono essere pubblicati.
    • Ecco alcuni esempi di consigli non personalizzati:
      • I 10 libri più letti di quest'anno.
      • Film appena usciti.
      • Podcast di tendenza.
  • Pubblica una scheda di accesso.
    • Per incoraggiare gli utenti ad accedere all'app, gli sviluppatori possono scegliere di pubblicare una scheda di accesso insieme al cluster di suggerimenti non personalizzati. Consulta la sezione di seguito per ulteriori dettagli su come pubblicare una scheda di accesso.
Tipo di consiglio Strategia di aggiornamento dei contenuti Linee guida relative all'aggiornamento dei contenuti
Consigli non personalizzati

Indigente

Consigliamo di aggiornare i suggerimenti una volta al giorno.

 Poiché gli utenti non hanno un'idea precisa di quali saranno i contenuti dei suggerimenti, la strategia di aggiornamento dei contenuti può essere indulgente.
Scheda di accesso nei consigli

Rigorosa

Consigliamo di aggiornare lo stato della scheda di accesso quando gli utenti escono dall'app sviluppatore.

Dopo che gli utenti hanno eseguito l'accesso, gli sviluppatori devono eliminare la carta chiamando l'API deleteUserManagementCluster().

È importante che lo stato di accesso sia sincronizzato con la piattaforma Google. Per un utente è confuso vedere una scheda di accesso sulla piattaforma Google dopo che ha già eseguito l'accesso. Pertanto, la strategia di aggiornamento dei contenuti deve essere rigorosa.

Cluster di continuazione

Durante la pubblicazione di cluster di continuazione, gli sviluppatori devono valutare se l'utente ha eseguito l'accesso o meno all'applicazione dello sviluppatore.

Quando l'utente ha eseguito l'accesso

  • I cluster di continuazione generati dagli utenti devono essere pubblicati.
    • Ecco alcuni esempi di cluster di continuazione generati dagli utenti:
      • Continua a guardare dal punto in cui l'utente ha interrotto la visione.
      • Continua a leggere dal punto in cui l'utente l'aveva interrotto.
Tipo di continuazione Strategia di aggiornamento dei contenuti Linee guida relative all'aggiornamento dei contenuti
Cluster di continuazione generati dall'utente

Rigorosa

Ti consigliamo di aggiornare la raccolta di contenuti quando gli utenti escono dall'app per sviluppatori.

 È importante che questi contenuti siano sincronizzati con i dati visualizzati sulle piattaforme Google. Questo perché, a differenza dei consigli personalizzati, l'utente si aspetta un insieme esatto di contenuti. Qualsiasi ritardo significativo nella pubblicazione può confondere gli utenti. Pertanto, la strategia di aggiornamento dei contenuti deve essere rigorosa.

Se l'utente non ha eseguito l'accesso

I percorsi di continuazione sono pensati principalmente per gli utenti che hanno eseguito l'accesso; tuttavia, puoi anche pubblicare cluster di continuazione per utenti che non hanno eseguito l'accesso se la tua app supporta le sessioni guest.

Cluster gestione utenti

L'obiettivo principale del cluster di gestione degli utenti è spronare gli utenti a eseguire determinate azioni sull'app del provider. L'azione di accesso indirizza gli utenti alla pagina di accesso dell'app affinché quest'ultima possa pubblicare contenuti (o fornire contenuti più personalizzati)

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

Immagini di proporzioni 16:9 con una risoluzione di 1264 x 712
Titolo Facoltativo - Se non viene fornita, è necessario fornire l'immagine Titolo sulla scheda
Testo 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()

appEngagePublishClient.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();

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

Dopo che gli utenti hanno eseguito l'accesso, gli sviluppatori devono eliminare la carta chiamando l'API deleteUserManagementCluster().

Aggiorna stato pubblicazione

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

  • Fornire lo stato in tutti gli scenari, anche quando i contenuti sono pubblicati (STATUS == PUBLISHED), è 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 è interrotto (STATUS == NOT_PUBLISHED), Google può evitare di attivare avvisi nelle dashboard di stato 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 sulla data di pubblicazione dei dati e su quando vengono pubblicati.
  • Google può utilizzare i codici di stato per sollecitare l'utente a eseguire determinate azioni nell'app in modo che possa vederne 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 sono stati pubblicati perché un utente non ha eseguito l'accesso, ti consigliamo 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 updatePubblicaStatus 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());

WorkManager per la pubblicazione dei cluster

Ti consigliamo di utilizzare WorkManager per pubblicare i cluster, poiché è la soluzione consigliata per il lavoro in background in cui l'esecuzione deve essere sia opportunistica sia garantita.

  • WorkManager esegue le operazioni in background il prima possibile.
  • WorkManager gestisce la logica per iniziare il lavoro in diverse condizioni, anche se un utente esce dalla tua app.

Quando l'utente esce dall'app, consigliamo di avviare un job in background che pubblichi cluster di continuazione insieme a cluster di suggerimenti. Un buon punto per gestire questa logica è Activity.onStop(), che viene chiamato quando l'utente esce dall'app.

Ti consigliamo di utilizzare PeriodicWorkRequest per pianificare un job ricorrente che pubblica cluster ogni 24 ore. Utilizzando un criterio CANCEL_AND_REENQUEUE per attivare il lavoro, gli sviluppatori possono assicurarsi che WorkManager invii i dati aggiornati ogni volta che un utente esce dall'app. Ciò contribuisce a impedire agli utenti di visualizzare dati inattivi.

Lo dimostra l'esempio seguente:

// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {

   public PublishClusters(Context appContext, WorkerParameters workerParams) {
       super(appContext, workerParams);
   }

   @NonNull
   @Override
   public Result doWork() {
       // publish clusters
   }
   ...
}

public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
       new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
          .addTag("Publish Clusters to Entertainment Space")
          .build();

// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
     "publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
     ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);

}

Gestire gli intent di trasmissione

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

Tuttavia, gli sviluppatori devono fare attenzione a non fare affidamento esclusivamente sulle trasmissioni, perché vengono attivate solo in determinati scenari, principalmente per la riattivazione dell'app e per forzare una sincronizzazione dei dati. Vengono attivati solo quando il servizio Engage determina che i contenuti potrebbero essere inattivi. In questo modo, c'è una maggiore fiducia nell'esperienza dell'utente sui contenuti, anche se l'applicazione non è aperta da molto tempo.

BroadcastReceiver deve essere configurato nei due modi seguenti:

  • Registra in modo dinamico un'istanza della classe BroadcastReceiver utilizzando Context.registerReceiver(). Ciò consente la comunicazione da applicazioni che sono ancora presenti in memoria.
  • 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.