Engage SDK Listen : instructions d'intégration technique tierce

Google est en train de développer une surface sur appareil, qui organisera les applications des utilisateurs par secteurs et offrira une nouvelle expérience immersive permettant une consommation et une découverte personnalisées du contenu de ces applications. Cette expérience plein écran donnera aux développeurs partenaires la possibilité de présenter leurs meilleurs contenus enrichis sur une chaîne dédiée en dehors de leur application.

Ce guide explique aux développeurs partenaires comment intégrer leur contenu audio à l'aide du SDK Engage dans le but de pouvoir renseigner cette nouvelle surface et les surfaces Google existantes.

Détails de l'intégration

Terminologie

Cette intégration comprend les trois types de clusters suivants : Recommendation (Recommandations), Continuation (Suite) et Featured (Sélection).

• Les clusters Recommendation affichent des suggestions personnalisées de contenus à lire provenant d'un développeur partenaire individuel.

  Les recommandations présentent la structure suivante :

  • Cluster "Recommendation" : vue de l'interface utilisateur contenant un groupe de recommandations du même développeur partenaire.

    

    Figure 1. Interface utilisateur d'Entertainment Space montrant le cluster "Recommendation" d'un seul partenaire

  • Entité : objet représentant un seul élément dans un cluster. Une entité peut être une playlist, un livre audio, un podcast, etc. Consultez la section Fournir les données d'entité pour obtenir la liste des types d'entités acceptés.

    

    Figure 2. Interface utilisateur d'Entertainment Space montrant une seule entité dans le cluster "Recommandations" d'un seul partenaire

• Le cluster Suite affiche dans un regroupement d'UI le contenu audio de plusieurs partenaires développeurs, contenu avec lequel les utilisateurs ont interagi récemment. Chaque développeur partenaire est autorisé à diffuser au maximum 10 entités dans le cluster "Suite".

  

  Figure 3. Interface utilisateur d'Entertainment Space montrant un cluster "Continuation" avec des recommandations de livres audio inachevés provenant de plusieurs partenaires (une seule recommandation est actuellement visible)

• Le cluster Sélection affiche une sélection d'articles de plusieurs développeurs partenaires dans un regroupement d'UI. Il n'existe qu'un seul cluster "Sélection", situé dans la partie supérieure de l'UI avec un emplacement prioritaire au-dessus de tous les clusters "Recommandations". Chaque développeur partenaire est autorisé à diffuser jusqu'à 10 entités dans le cluster "Sélection".

  

  Figure 4. Interface utilisateur d'Entertainment Space montrant un cluster "Featured" et un cluster "Recommendation" de plusieurs partenaires (une seule recommandation est actuellement visible)

Travail préalable

Niveau d'API minimal : 19

Ajoutez la bibliothèque com.google.android.play:engage à votre application :

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

Résumé

La conception repose sur l'implémentation d'un service lié.

Les données qu'un client peut publier sont soumises aux limites suivantes pour chaque type de cluster :

Type de cluster	Nombre limite de clusters	Limites maximales d'entités dans un cluster
Cluster(s) "Recommendation"	5 maximum	50 maximum
Cluster "Continuation"	1 maximum	10 maximum
Cluster "Featured"	1 maximum	10 maximum

Étape 1 : Fournir les données d'entité

Le SDK a défini différentes entités pour représenter chaque type d'élément. Nous prenons en charge les entités suivantes pour la catégorie Listen (Écouter) :

1. MusicAlbumEntity
2. MusicArtistEntity
3. MusicTrackEntity
4. MusicVideoEntity
5. PlaylistEntity
6. PodcastSeriesEntity
7. PodcastEpisodeEntity
8. LiveRadioStationEntity
9. AudiobookEntity

Les tableaux ci-dessous décrivent les attributs disponibles pour chaque type et indiquent s'ils sont obligatoires.

MusicAlbumEntity

L'objet MusicAlbumEntity représente un album musical (par exemple, Midnights de Taylor Swift).

Attribut	Obligatoire ?	Notes
Nom	Obligatoire	Titre de l'album musical.
Images poster	Obligatoire	Vous devez fournir au moins une image. Consultez la section Caractéristiques des images pour en savoir plus.
URI de la page d'informations	Obligatoire	Lien profond vers l'application du fournisseur pour en savoir plus sur l'album musical. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Artistes	Obligatoire	Liste des artistes de l'album musical.
URI de lecture	Facultatif	Lien profond permettant de lancer la lecture de l'album dans l'application du fournisseur. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Description	Facultatif	Ne doit pas dépasser 200 caractères.
Nombre de titres	Facultatif	Nombre de titres de l'album.
Genres	Facultatif	Liste des genres de l'album musical.
Format de l'album	Facultatif	ALBUM (LP et double LP) EP SINGLE Mix
Maisons de disques	Facultatif	Liste des maisons de disques associées à l'album.
Téléchargé sur l'appareil	Facultatif	Booléen indiquant si l'album de musique est téléchargé sur l'appareil.
Contenu explicite	Facultatif	Booléen indiquant si le contenu est explicite ou non Les articles comportant du contenu explicite ou faisant l'objet d'un avertissement parental doivent être définis sur "TRUE". Les éléments explicites sont signalés par un tag "E".
Date de sortie	Facultatif	Date de sortie de l'album, en millisecondes.
Durée	Facultatif	Durée de l'album en millisecondes.
Durée du dernier engagement	Facultatif	Recommandé pour les éléments du cluster "Continuation". Peut être utilisé pour le classement. En millisecondes (epoch)
Pourcentage de contenu déjà écouté	Facultatif	Recommandé pour les éléments du cluster "Continuation". Nombre entier compris entre 0 et 100

MusicArtistEntity

L'objet MusicArtistEntity représente un artiste musical (Adele, par exemple).

Attribut	Obligatoire ?	Notes
Nom	Obligatoire	Nom de l'artiste musical.
Images poster	Obligatoire	Vous devez fournir au moins une image. Consultez la section Caractéristiques des images pour en savoir plus.
URI de la page d'informations	Obligatoire	Lien profond vers l'application du fournisseur pour en savoir plus sur l'artiste musical. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
URI de lecture	Facultatif	Lien profond qui lance la lecture des titres de l'artiste dans l'application du fournisseur. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Description	Facultatif	Ne doit pas dépasser 200 caractères.
Durée du dernier engagement	Facultatif	Recommandé pour les éléments du cluster "Continuation". Peut être utilisé pour le classement. En millisecondes (epoch)

MusicTrackEntity

L'objet MusicTrackEntity représente un titre musical (par exemple, Yellow de Coldplay).

Attribut	Obligatoire ?	Notes
Nom	Obligatoire	Titre du morceau.
Images poster	Obligatoire	Vous devez fournir au moins une image. Consultez la section Caractéristiques des images pour en savoir plus.
URI de lecture	Obligatoire	Lien profond qui lance la lecture du titre musical dans l'application du fournisseur. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
URI de la page d'informations	Facultatif	Lien profond vers l'application du fournisseur pour en savoir plus sur le titre musical. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Description	Facultatif	Ne doit pas dépasser 200 caractères.
Durée	Facultatif	Durée du titre en millisecondes.
Album	Facultatif	Nom de l'album auquel le titre appartient.
Artistes	Obligatoire	Liste des artistes impliqués dans le titre musical.
Téléchargé sur l'appareil	Facultatif	Booléen indiquant si le titre musical est téléchargé sur l'appareil.
Contenu explicite	Facultatif	Booléen indiquant si le contenu est explicite ou non Les articles comportant du contenu explicite ou faisant l'objet d'un avertissement parental doivent être définis sur "TRUE". Les éléments explicites sont signalés par un tag "E".
Durée du dernier engagement	Facultatif	Recommandé pour les éléments du cluster "Continuation". Peut être utilisé pour le classement. En millisecondes (epoch)
Pourcentage de contenu déjà écouté	Facultatif	Recommandé pour les éléments du cluster "Continuation". Nombre entier compris entre 0 et 100

MusicVideoEntity

L'objet MusicVideoEntity représente un clip musical (par exemple, The Weeknd – Take My Breath (Clip musical officiel)).

Attribut	Obligatoire ?	Notes
Nom	Obligatoire	Titre du clip musical.
Images poster	Obligatoire	Vous devez fournir au moins une image. Consultez la section Caractéristiques des images pour en savoir plus.
URI de lecture	Obligatoire	Lien profond qui lance la lecture du clip musical dans l'application du fournisseur. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
URI de la page d'informations	Facultatif	Lien profond vers l'application du fournisseur pour en savoir plus sur le clip musical. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Durée	Facultatif	Durée de la vidéo en millisecondes.
Nombre de vues	Facultatif	Nombre de vues de la vidéo au format texte libre.
Artistes	Facultatif	Liste des artistes du clip musical.
Classification du contenu	Facultatif	Liste des classifications de contenu du titre.
Description	Facultatif	Ne doit pas dépasser 200 caractères.
Téléchargé sur l'appareil	Facultatif	Booléen indiquant si le clip musical est téléchargé sur l'appareil.
Contenu explicite	Facultatif	Booléen indiquant si le contenu est explicite ou non Les articles comportant du contenu explicite ou faisant l'objet d'un avertissement parental doivent être définis sur "TRUE". Les éléments explicites sont signalés par un tag "E".
Durée du dernier engagement	Facultatif	Recommandé pour les éléments du cluster "Continuation". Peut être utilisé pour le classement. En millisecondes (epoch)
Pourcentage de contenu déjà écouté	Facultatif	Recommandé pour les éléments du cluster "Continuation". Nombre entier compris entre 0 et 100

PlaylistEntity

L'objet PlaylistEntity représente une playlist musicale (par exemple, la playlist "Top 10" en France).

Attribut	Obligatoire ?	Notes
Nom	Obligatoire	Titre de la playlist.
Images poster	Obligatoire	Vous devez fournir au moins une image. Consultez la section Caractéristiques des images pour en savoir plus.
URI de lecture	Obligatoire	Lien profond permettant de lancer la playlist musicale dans l'application du fournisseur. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
URI de la page d'informations	Facultatif	Lien profond vers l'application du fournisseur pour en savoir plus sur la playlist musicale. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Durée	Facultatif	Durée de la playlist en millisecondes.
Nombre de titres	Facultatif	Nombre de titres dans la playlist musicale.
Description	Facultatif	Ne doit pas dépasser 200 caractères.
Téléchargé sur l'appareil	Facultatif	Booléen indiquant si la playlist est téléchargée sur l'appareil.
Contenu explicite	Facultatif	Booléen indiquant si le contenu est explicite ou non Les articles comportant du contenu explicite ou faisant l'objet d'un avertissement parental doivent être définis sur "TRUE". Les éléments explicites sont signalés par un tag "E".
Durée du dernier engagement	Facultatif	Recommandé pour les éléments du cluster "Continuation". Peut être utilisé pour le classement. En millisecondes (epoch)
Pourcentage de contenu déjà écouté	Facultatif	Recommandé pour les éléments du cluster "Continuation". Nombre entier compris entre 0 et 100

PodcastSeriesEntity

L'objet PodcastSeriesEntity représente une série de podcasts (par exemple, This American Life).

Attribut	Obligatoire ?	Notes
Nom	Obligatoire	Titre de la série de podcasts.
Images poster	Obligatoire	Vous devez fournir au moins une image. Consultez la section Caractéristiques des images pour en savoir plus.
URI de la page d'informations	Obligatoire	Lien profond vers l'application du fournisseur pour en savoir plus sur la série de podcasts. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
URI de lecture	Facultatif	Lien profond qui lance la lecture de la série de podcasts dans l'application du fournisseur. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Nombre d'épisodes	Facultatif	Nombre d'épisodes de la série de podcasts.
Nom de la production	Facultatif	Nom de la production de la série de podcasts.
Animateurs	Facultatif	Liste des animateurs de la série de podcasts.
Genres	Facultatif	Liste des genres de séries de podcasts.
Téléchargé sur l'appareil	Facultatif	Booléen indiquant si le podcast est téléchargé sur l'appareil.
Description	Facultatif	Ne doit pas dépasser 200 caractères.
Contenu explicite	Facultatif	Booléen indiquant si le contenu est explicite ou non Les articles comportant du contenu explicite ou faisant l'objet d'un avertissement parental doivent être définis sur "TRUE". Les éléments explicites sont signalés par un tag "E".
Durée du dernier engagement	Facultatif	Recommandé pour les éléments du cluster "Continuation". Peut être utilisé pour le classement. En millisecondes (epoch)

PodcastEpisodeEntity

L'objet PodcastEpisodeEntity représente un épisode de podcast (par exemple, Spark Bird, Épisode 754 : This American Life).

Attribut	Obligatoire ?	Notes
Nom	Obligatoire	Titre de l'épisode du podcast.
Images poster	Obligatoire	Vous devez fournir au moins une image. Consultez la section Caractéristiques des images pour en savoir plus.
URI de lecture	Obligatoire	Lien profond qui lance la lecture de l'épisode de podcast dans l'application du fournisseur. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Titre de la série pour la production	Obligatoire	Nom de la série de podcasts à laquelle appartient l'épisode.
Durée	Obligatoire	Durée de l'épisode de podcast en millisecondes.
Date de publication	Obligatoire	Date de publication du podcast en millisecondes (epoch)
URI de la page d'informations	Facultatif	Lien profond vers l'application du fournisseur pour en savoir plus sur l'épisode du podcast. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Nom de la production	Facultatif	Nom de la production de la série de podcasts.
Indice de l'épisode	Facultatif	Indice de l'épisode de la série (le premier indice est 1).
Animateurs	Facultatif	Liste des animateurs de l'épisode de podcast.
Genres	Facultatif	Liste des genres de l'épisode de podcast.
Téléchargé sur l'appareil	Facultatif	Booléen indiquant si l'épisode de podcast est téléchargé sur l'appareil.
Description	Facultatif	Ne doit pas dépasser 200 caractères.
Podcast vidéo	Facultatif	Booléen indiquant si l'épisode de podcast comporte du contenu vidéo
Contenu explicite	Facultatif	Booléen indiquant si le contenu est explicite ou non Les articles comportant du contenu explicite ou faisant l'objet d'un avertissement parental doivent être définis sur "TRUE". Les éléments explicites sont signalés par un tag "E".
Type d'écoute suivant	Facultatif	Recommandé pour les éléments du cluster "Continuation". TYPE_CONTINUE : reprendre la lecture d'un élément audio mis en pause. TYPE_NEXT : poursuivre avec le nouveau contenu d'une série. TYPE_NEW : nouveauté.
Durée du dernier engagement	Facultatif	Recommandé pour les éléments du cluster "Continuation". Peut être utilisé pour le classement. En millisecondes (epoch)
Pourcentage de contenu déjà écouté	Facultatif	Recommandé pour les éléments du cluster "Continuation". Nombre entier compris entre 0 et 100

LiveRadioStationEntity

L'objet LiveRadioStationEntity représente une station de radio en direct (par exemple, 98.1 The Breeze).

Attribut	Obligatoire ?	Notes
Nom	Obligatoire	Titre de la station de radio en direct.
Images poster	Obligatoire	Vous devez fournir au moins une image. Consultez la section Caractéristiques des images pour en savoir plus.
URI de lecture	Obligatoire	Lien profond permettant de lancer la station de radio dans l'application du fournisseur. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
URI de la page d'informations	Facultatif	Lien profond vers l'application du fournisseur pour en savoir plus sur la station de radio. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Fréquence	Facultatif	Fréquence de diffusion de la station de radio (par exemple, "98.1 FM").
Titre de l'émission	Facultatif	Émission en cours de lecture sur la station de radio.
Animateurs	Facultatif	Liste des animateurs de la station de radio.
Description	Facultatif	Ne doit pas dépasser 200 caractères.
Durée du dernier engagement	Facultatif	Recommandé pour les éléments du cluster "Continuation". Peut être utilisé pour le classement. En millisecondes (epoch)

AudiobookEntity

L'objet AudiobookEntity représente un livre audio (par exemple, le livre audio Becoming de Michelle Obama).

Attribut	Obligatoire ?	Notes
Nom	Obligatoire
Images poster	Obligatoire	Vous devez fournir au moins une image. Consultez la section Caractéristiques des images pour en savoir plus.
Auteur	Obligatoire	Vous devez indiquer au moins un nom d'auteur.
Narrateur	Obligatoire	Vous devez indiquer au moins un nom de narrateur.
URI du lien d'action	Obligatoire	Lien profond vers l'application du fournisseur pour le livre audio. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes.
Date de publication	Facultatif	En millisecondes (epoch), le cas échéant
Description	Facultatif	Ne doit pas dépasser 200 caractères.
Prix	Facultatif	Texte libre
Durée	Facultatif	Cette valeur doit être positive, le cas échéant.
Genre	Facultatif	Liste des genres associés au livre.
Nom de la série	Facultatif	Nom de la série à laquelle appartient le livre audio (par exemple, Harry Potter).
Indice des unités de la série	Facultatif	Indice du livre audio de la série, où 1 correspond au premier livre audio de la série. Par exemple, si Harry Potter et le Prisonnier d'Azkaban est le troisième livre de la série, cette valeur doit être 3.
Type de reprise de livre	Facultatif	TYPE_CONTINUE : reprendre un livre non terminé. TYPE_NEXT : poursuivre avec le nouveau contenu d'une série. TYPE_NEW : nouveauté.
Durée du dernier engagement	Obligatoire sous certaines conditions	Doit être fourni lorsque l'élément se trouve dans le cluster "Continuation". En millisecondes (epoch)
Pourcentage de contenu déjà lu	Obligatoire sous certaines conditions	Doit être fourni lorsque l'élément se trouve dans le cluster "Continuation". Les livres audio *récemment* acquis peuvent faire partie du cluster "Continue reading". La valeur doit être supérieure à 0 et inférieure à 100.
DisplayTimeWindow : définissez la période d'affichage d'un contenu sur une surface.
Code temporel de début	Facultatif	Code temporel de l'epoch après lequel le contenu doit être affiché sur la surface. Si ce code n'est pas configuré, le contenu peut s'afficher sur la surface. En millisecondes (epoch)
Code temporel de fin	Facultatif	Code temporel de l'epoch après lequel le contenu n'est plus affiché sur la surface. Si ce code n'est pas configuré, le contenu peut s'afficher sur la surface. En millisecondes (epoch)

Caractéristiques des images

Vous trouverez ci-dessous les spécifications requises pour les composants Image :

Format	Obligatoire ?	Nombre minimal de pixels	Nombre de pixels recommandé
Carré (1x1)	Obligatoire	300 x 300	1 200 x 1 200
Paysage (1,91 x 1)	Facultatif	600 x 314	1 200 x 628
Format portrait (4 x 5)	Facultatif	480 x 600	960 x 1200

Formats des fichiers

PNG, JPG, GIF statique, WebP

Taille maximale des fichiers

5 120 Ko

Autres recommandations

• Zone de sécurité de l'image : placez le contenu important dans les 80 % les plus au centre de l'image.

Exemples

MusicAlbumEntity musicAlbumEntity =
        new MusicAlbumEntity.Builder()
            .setName(NAME)
             .addPosterImage(new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(960)
                  .setImageWidthInPixel(408)
                  .build())
            .setPlayBackUri("https://play.google/album/play")
            .setInfoPageUri("https://play.google/album/info")
            .setDescription("A description of this album.")
            .addArtist("Artist")
            .addGenre("Genre")
            .addMusicLabel("Label")
            .addContentRating("Rating")
            .setSongsCount(960)
            .setReleaseDateEpochMillis(1633032895L)
            .setDurationMillis(1633L)
            .build();

AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(new Image.Builder()
                 .setImageUri(Uri.parse("http://www.x.com/image.png"))
                 .setImageHeightInPixel(960)
                 .setImageWidthInPixel(408)
                  .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(
               Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

Étape 2 : Fournir les données de cluster

Il est recommandé d'exécuter la tâche de publication de contenu en arrière-plan (par exemple, à l'aide de WorkManager) et de la programmer régulièrement ou sur la base d'un événement précis (par exemple, chaque fois que l'utilisateur ouvre l'application ou lorsqu'il vient d'ajouter quelque chose à son panier).

AppEngagePublishClient permet la publication des clusters. Les API suivantes sont disponibles dans le client :

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishContinuationCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteContinuationCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

Cette API permet de vérifier si le service est disponible pour l'intégration et de déterminer si le contenu peut être présenté sur l'appareil.

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.
    }
});

Remarque : Nous vous recommandons vivement d'exécuter une tâche périodique pour vérifier si le service deviendra disponible ultérieurement. La disponibilité du service peut changer avec les mises à niveau d'Android, les mises à niveau d'applications, ainsi qu'avec les installations et les désinstallations. Effectuer des vérifications au moyen d'une tâche périodique selon un intervalle de temps spécifique permettra de publier les données une fois le service disponible.

publishRecommendationClusters

Cette API permet de publier une liste d'objets RecommendationCluster.

Important : Les API de publication sont des API upsert. Elles remplacent le contenu existant. N'appelez pas des API de suppression et de publication par la suite pour remplacer le contenu, car les API de publication le font intrinsèquement.

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build());

Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :

• Les données RecommendationCluster existantes du développeur partenaire sont supprimées.
• Les données de la requête sont analysées et stockées dans le cluster "Recommendation" mis à jour.

En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

publishFeaturedCluster

Cette API permet de publier une liste d'objets FeaturedCluster.

Important : Les API de publication sont des API upsert. Elles remplacent le contenu existant. N'appelez pas des API de suppression et de publication par la suite pour remplacer le contenu, car les API de publication le font intrinsèquement.

Kotlin

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :

• Les données FeaturedCluster existantes du développeur partenaire sont supprimées.
• Les données de la requête sont analysées et stockées dans le cluster "Featured" mis à jour.

En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

publishContinuationCluster

Cette API permet de publier un objet ContinuationCluster.

Important : Les API de publication sont des API upsert. Elles remplacent le contenu existant. N'appelez pas des API de suppression et de publication par la suite pour remplacer le contenu, car les API de publication le font intrinsèquement.

Kotlin

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

Java

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :

• Les données ContinuationCluster existantes du développeur partenaire sont supprimées.
• Les données de la requête sont analysées et stockées dans le cluster "Continuation" mis à jour.

En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

publishUserAccountManagementRequest

Cette API permet de publier une fiche de connexion. 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é).

Les métadonnées suivantes font partie de la fiche de connexion :

Attribut	Obligatoire ?	Description
URI d'action	Obligatoire	Lien profond vers l'action (par exemple, accès à la page de connexion de l'application)
Image	Facultatif : si aucun titre n'est fourni, vous devez en fournir un	Image affichée sur la fiche Images au format 16:9 avec une résolution de 1 264 x 712
Titre	Facultatif : si aucune image n'est fournie, vous devez en fournir une	Titre sur la fiche
Texte de l'action	Facultatif	Texte affiché sur l'incitation à l'action (par exemple, "Se connecter")
Sous-titre	Facultatif	Sous-titre facultatif sur la fiche

Important : Les API de publication sont des API upsert. Elles remplacent le contenu existant. N'appelez pas des API de suppression et de publication par la suite pour remplacer le contenu, car les API de publication le font intrinsèquement.

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

Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :

• Les données UserAccountManagementCluster existantes du développeur partenaire sont supprimées.
• Les données de la requête sont analysées et stockées dans le cluster "UserAccountManagementCluster" mis à jour.

En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

updatePublishStatus

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é, Google vous recommande 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.

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

Cette API permet de supprimer le contenu des clusters "Recommendation".

Important : Les API de suppression ne doivent être appelées que lorsqu'il n'y a pas de contenu à publier. N'appelez pas des API de suppression et de publication par la suite pour remplacer le contenu, car les API de publication le font intrinsèquement. Contactez engage-developers@ avant d'utiliser des API de suppression.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

Lorsque le service reçoit la requête, il supprime les données existantes des clusters "Recommendation". En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

Remarque : Cette API est disponible à partir de la version 1.1.0.

deleteFeaturedCluster

Cette API permet de supprimer le contenu du cluster "Featured".

Important : Les API de suppression ne doivent être appelées que lorsqu'il n'y a pas de contenu à publier. N'appelez pas des API de suppression et de publication par la suite pour remplacer le contenu, car les API de publication le font intrinsèquement. Contactez engage-developers@ avant d'utiliser des API de suppression.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Lorsque le service reçoit la requête, il supprime les données existantes du cluster "Featured". En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

Remarque : Cette API est disponible à partir de la version 1.1.0.

deleteContinuationCluster

Cette API permet de supprimer le contenu du cluster "Continuation".

Important : Les API de suppression ne doivent être appelées que lorsqu'il n'y a pas de contenu à publier. N'appelez pas des API de suppression et de publication par la suite pour remplacer le contenu, car les API de publication le font intrinsèquement. Contactez engage-developers@ avant d'utiliser des API de suppression.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

Lorsque le service reçoit la requête, il supprime les données existantes du cluster "Continuation". En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

Remarque : Cette API est disponible à partir de la version 1.1.0.

deleteUserManagementCluster

Cette API permet de supprimer le contenu du cluster "UserAccountManagement".

Important : Les API de suppression ne doivent être appelées que lorsqu'il n'y a pas de contenu à publier. N'appelez pas des API de suppression et de publication par la suite pour remplacer le contenu, car les API de publication le font intrinsèquement. Contactez engage-developers@ avant d'utiliser des API de suppression.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Lorsque le service reçoit la requête, il supprime les données existantes du cluster "UserAccountManagement". En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

Remarque : Cette API est disponible à partir de la version 1.1.0.

deleteClusters

Cette API permet de supprimer le contenu d'un type de cluster donné.

Important : Les API de suppression ne doivent être appelées que lorsqu'il n'y a pas de contenu à publier. N'appelez pas des API de suppression et de publication par la suite pour remplacer le contenu, car les API de publication le font intrinsèquement. Contactez engage-developers@ avant d'utiliser des API de suppression.

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

Lorsque le service reçoit la requête, il supprime les données existantes de tous les clusters correspondant aux types de clusters spécifiés. Les clients peuvent choisir de transmettre un ou plusieurs types de clusters. En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

Gestion des exceptions

Il est fortement recommandé d'écouter le résultat de la tâche à partir des API de publication afin qu'une action de suivi puisse être effectuée pour récupérer et renvoyer une tâche réussie.

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'erreur est renvoyée au format AppEngageException. La cause est incluse sous la forme d'un code d'erreur.

Code d'erreur	Remarque
SERVICE_NOT_FOUND	Le service n'est pas disponible sur l'appareil donné.
SERVICE_NOT_AVAILABLE	Le service est disponible sur l'appareil donné, mais pas au moment de l'appel (par exemple, il est explicitement désactivé).
SERVICE_CALL_EXECUTION_FAILURE	L'exécution de la tâche a échoué en raison de problèmes de thread. Dans ce cas, vous pouvez réessayer.
SERVICE_CALL_PERMISSION_DENIED	L'appelant n'est pas autorisé à effectuer l'appel du service.
SERVICE_CALL_INVALID_ARGUMENT	La requête contient des données non valides (par exemple, un nombre plus élevé que le nombre de clusters autorisé).
SERVICE_CALL_INTERNAL	Une erreur s'est produite au niveau du service.
SERVICE_CALL_RESOURCE_EXHAUSTED	L'appel du service est effectué trop fréquemment.

Étape 3 : 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.

L'objectif des intents de diffusion est principalement de réactiver des applications et de forcer la synchronisation des données. Les intents de diffusion ne sont pas conçus pour être envoyés très fréquemment. Ils ne se déclenchent que lorsque le service Engage détermine que le contenu est peut-être obsolète (par exemple, s'il date d'il y a une semaine). 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.

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 continuation cluster publish when PUBLISH_CONTINUATION 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 Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}

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

<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.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

Les intents suivants sont envoyés par le service :

• com.google.android.engage.action.PUBLISH_RECOMMENDATION Nous vous recommandons de démarrer un appel publishRecommendationClusters lorsque vous recevez cet intent.
• com.google.android.engage.action.PUBLISH_FEATURED Nous vous recommandons de démarrer un appel publishFeaturedCluster lors de la réception de cet intent.
• com.google.android.engage.action.PUBLISH_CONTINUATION Nous vous recommandons de démarrer un appel publishContinuationCluster lors de la réception de cet intent.

Workflow d'intégration

Pour vous procurer un guide par étapes sur la validation de votre intégration une fois celle-ci terminée, consultez la page Workflow d'intégration pour les développeurs d'Engage.

Questions fréquentes

Pour en savoir plus, consultez les questions fréquentes concernant le SDK Engage.

Contact

Veuillez contacter [e-mail] si vous avez des questions au cours du processus d'intégration. Notre équipe vous répondra dès que possible.

Étapes suivantes

Une fois cette intégration effectuée, procédez comme suit :

• Envoyez un e-mail à l'adresse [e-mail] et joignez-y votre APK intégré prêt à être testé par Google.
• Google effectuera une vérification et un examen en interne pour s'assurer que l'intégration fonctionne comme prévu. Si des modifications sont nécessaires, nous vous contacterons avec toutes les informations nécessaires.
• Une fois les tests terminés, si aucune modification n'est nécessaire, nous vous informerons que vous pouvez commencer à publier le fichier APK mis à jour et intégré sur le Play Store.
• Une fois que nous aurons confirmé la publication de votre APK mis à jour sur le Play Store, vos clusters Recommendation (Recommandations), Featured (Sélection) et Continuation (Suite) seront publiés et visibles par les utilisateurs.