Consignes de publication des clusters du SDK Engage

Ce guide comprend un ensemble de consignes de publication des clusters que les développeurs peuvent utiliser lors de l'intégration avec le SDK Engage.

Clusters "Recommandations"

Titre du cluster

Nous vous recommandons de fournir un titre de cluster unique et pertinent qui donne aux utilisateurs plus d'informations sur le contenu de ce cluster.

Voici quelques exemples de titres de clusters appropriés en fonction du contenu :

• Clusters spécifiques à la vente
  • Offres éclair
  • Les bons plans de la semaine
  • En lien avec votre achat de Pixel Buds
  • Bottes pour femmes
• Clusters de livres sur la santé
  • Santé, corps et esprit
  • Recommandations personnalisées dans le domaine de la santé
  • Meilleures ventes dans la catégorie "Remise en forme"

Contenu du cluster

Lors de la publication des clusters "Recommandations", les développeurs doivent déterminer si l'utilisateur est connecté ou non à leur application.

Lorsque l'utilisateur est connecté

Si l'utilisateur est connecté à l'application du développeur, nous recommandons de publier des clusters de contenu personnalisés ou générés par l'utilisateur. Étant donné que les contenus personnalisés et générés par l'utilisateur sont plus pertinents, les internautes sont plus enclins à accéder à l'application du développeur depuis la surface Google.

• Vous pouvez publier des recommandations personnalisées.
  • Voici quelques exemples de recommandations personnalisées :
    • Coups de cœur basés sur l'historique des vidéos regardées de l'utilisateur
    • Livres semblables à ceux figurant dans l'historique de lecture de l'utilisateur
    • Titres des artistes préférés de l'utilisateur
• Les bibliothèques de contenu généré par l'utilisateur peuvent être publiées.
  • Voici quelques exemples de bibliothèques de contenu généré par l'utilisateur :
    • Liste de l'utilisateur dans l'application du développeur
    • Liste auto-déclarée des artistes préférés de l'utilisateur dans l'application du développeur

Lorsque l'utilisateur n'est pas connecté

Si un utilisateur n'est pas connecté à l'application du développeur, nous recommandons tout de même de publier des clusters pour l'encourager à accéder à l'application du développeur depuis la surface Google.

• Les clusters de recommandations non personnalisées devraient être publiés.
  • Voici quelques exemples de recommandations non personnalisées :
    • Top 10 des livres les plus lus cette année
    • Nouveaux films
    • Meilleurs podcasts
• Publiez une fiche de connexion.
  • Afin d'encourager les utilisateurs à se connecter à leur application, les développeurs peuvent choisir de publier une fiche de connexion avec le cluster de recommandations non personnalisées. Consultez la section ci-dessous pour en savoir plus sur la publication d'une fiche de connexion.

Clusters "Continuation"

Lors de la publication des clusters "Continuation", les développeurs doivent déterminer si l'utilisateur est connecté ou non à leur application.

Lorsque l'utilisateur est connecté

• Les clusters "Continuation" générés par l'utilisateur devraient être publiés.
  • Voici quelques exemples de clusters "Continuation" générés par l'utilisateur :
    • Reprendre la vidéo là où l'utilisateur s'était arrêté
    • Continuer la lecture là où l'utilisateur s'était arrêté

Lorsque l'utilisateur n'est pas connecté

Les parcours de continuation sont principalement destinés aux utilisateurs connectés. Toutefois, vous pouvez également publier des clusters de continuation pour les utilisateurs déconnectés si votre application prend en charge des sessions Invité.

Cluster de gestion des utilisateurs

L'objectif principal du cluster de gestion des utilisateurs est d'inciter les utilisateurs à effectuer certaines actions sur l'application du fournisseur. L'action de connexion redirige les utilisateurs vers la page de connexion de l'application afin que celle-ci puisse publier du contenu (ou fournir un contenu plus personnalisé).

Fiche de connexion

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

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

Une fois que les utilisateurs se sont connectés, les développeurs doivent supprimer la fiche en appelant l'API deleteUserManagementCluster().

Mettre à jour l'état de publication

Si, pour une raison opérationnelle interne, aucun des clusters n'est publié, nous vous recommandons vivement de mettre à jour l'état de publication à l'aide de l'API updatePublishStatus. Ce point est important pour les raisons suivantes :

• Il est essentiel d'indiquer l'état dans tous les scénarios, même lorsque le contenu est publié (STATUS == PUBLISHED) pour renseigner les tableaux de bord qui utilisent cet état explicite afin de transmettre l'état et d'autres métriques de votre intégration.
• Si aucun contenu n'est publié, mais que l'état de l'intégration fonctionne correctement (STATUS == NOT_PUBLISHED), Google peut éviter de déclencher des alertes dans les tableaux de bord concernant l'état de l'application. Cela confirme que le contenu n'est pas publié en raison d'une situation attendue du point de vue du fournisseur.
• Cela permet aux développeurs de fournir des informations concernant la date de publication des données.
• Google peut utiliser les codes d'état pour encourager l'utilisateur à effectuer certaines actions dans l'application, afin qu'il puisse afficher ou contourner le contenu de l'application.

Voici la liste des codes d'état de publication éligibles :

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

Si le contenu n'est pas publié parce que l'utilisateur n'est pas connecté, nous vous recommandons de publier la fiche de connexion. Si, pour une raison quelconque, les fournisseurs ne peuvent pas publier la fiche de connexion, nous vous recommandons d'appeler l'API updatePublishStatus avec le code d'état NOT_PUBLISHED_REQUIRES_SIGN_IN.

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

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

WorkManager pour la publication de clusters

Nous vous conseillons d'utiliser WorkManager pour publier des clusters, car il s'agit de la solution recommandée pour les tâches d'arrière-plan dont l'exécution doit être à la fois opportuniste et garantie.

• WorkManager exécute le travail en arrière-plan dès que possible.
• Il gère la logique afin de démarrer le travail dans diverses conditions, même si un utilisateur quitte votre application.

Lorsque l'utilisateur quitte l'application, nous vous recommandons de démarrer une tâche en arrière-plan qui publiera des clusters "Continuation" avec les clusters "Recommandations". Activity.onStop(), qui est appelé lorsque l'utilisateur quitte l'application, est un bon point de départ pour gérer cette logique.

Nous vous suggérons d'utiliser PeriodicWorkRequest pour planifier une tâche récurrente qui publiera des clusters toutes les 24 heures. En utilisant une règle CANCEL_AND_REENQUEUE pour déclencher le travail, les développeurs peuvent s'assurer que WorkManager envoie les données mises à jour chaque fois qu'un utilisateur quitte l'application. Cela empêche les internautes de voir des données obsolètes.

En voici un bon exemple :

// 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);

}

Gérer les intents de diffusion

En plus d'effectuer des appels d'API de publication de contenu via une tâche, vous devez également configurer un objet BroadcastReceiver pour recevoir la requête de publication de contenu.

Toutefois, les développeurs doivent veiller à ne pas dépendre uniquement des diffusions, car elles ne sont déclenchées que dans certains scénarios, principalement pour la réactivation d'une application et pour forcer la synchronisation des données. Elles ne sont déclenchées que lorsque le service Engage détermine que le contenu peut être obsolète. De cette façon, l'utilisateur a plus de chances de bénéficier d'une expérience de contenu actualisée, même si l'application n'a pas été exécutée pendant une longue période.

Le BroadcastReceiver doit être configuré de deux manières :

• Enregistrez dynamiquement une instance de la classe BroadcastReceiver à l'aide de Context.registerReceiver(). Cela permet la communication à partir d'applications restées actives en mémoire.
• Déclarez une implémentation de manière statique avec la balise <receiver> dans le fichier AndroidManifest.xml. Cela permet à l'application de recevoir des intents de diffusion lorsqu'elle n'est pas en cours d'exécution, et de publier le contenu.