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 culinaire à 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 cinq types de clusters suivants : Recommendation (Recommandations), Featured (Sélection), Food Shopping Cart (Panier alimentaire), Food Shopping List (Liste de courses alimentaires) et Reorder (Réorganiser).
Les clusters Recommendation affichent des suggestions personnalisées d'un développeur partenaire individuel dans le domaine culinaire. Ces recommandations peuvent être personnalisées ou généralisées (par exemple, nouvelle promotion). Utilisez-les pour présenter des recettes, des magasins, des plats, des produits alimentaires, etc.
- Un cluster "Recommendation" peut être constitué de fiches
ProductEntity
,StoreEntity
ouRecipeEntity
, mais pas de types d'entités différents.
- Un cluster "Recommendation" peut être constitué de fiches
Le cluster Featured affiche une sélection d'entités de plusieurs développeurs partenaires dans un même groupe d'UI. Il n'existe qu'un seul cluster "Featured", situé dans la partie supérieure de l'UI avec un emplacement prioritaire au-dessus de tous les clusters "Recommendation". Chaque développeur partenaire est autorisé à diffuser jusqu'à 10 entités dans le cluster "Featured".
Le cluster Food Shopping Cart donne un aperçu des paniers d'épicerie de plusieurs développeurs partenaires dans un seul regroupement d'interface utilisateur, invitant les utilisateurs à finaliser leur panier en attente. Il n'y a qu'un seul cluster "Food Shopping Cart".
Il doit afficher le nombre total d'articles dans le panier et peut également inclure des images pour X articles dans le panier de l'utilisateur.
Le cluster Food Shopping List offre un aperçu des listes de courses de plusieurs développeurs partenaires dans un seul regroupement d'interface utilisateur, invitant les utilisateurs à revenir à l'application correspondante pour mettre à jour et finaliser leurs listes. Il n'y a qu'un seul cluster "Food Shopping List".
Le cluster Reorder donne un aperçu des commandes précédentes de plusieurs développeurs partenaires dans un seul regroupement d'interface utilisateur, invitant les utilisateurs à renouveler leur commande. Il n'y a qu'un seul cluster "Reorder".
Il doit afficher le nombre total d'articles de la commande précédente de l'utilisateur et doit également inclure l'un des éléments suivants :
- des images de X articles dans la commande précédente de l'utilisateur
- des étiquettes pour X articles dans la commande précédente de l'utilisateur
Travail préalable
Niveau d'API minimal : 19
Ajoutez la bibliothèque com.google.android.engage:engage-core
à 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.5.2'
}
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 | 25 maximum (ProductEntity , RecipeEntity ou StoreEntity ) |
Cluster "Featured" | 1 maximum | 10 maximum (ProductEntity , RecipeEntity ou StoreEntity ) |
Cluster "Food Shopping Cart" | 1 maximum | 1 ShoppingCartEntity maximum |
Cluster "Food Shopping List" | 1 maximum | 1 ShoppingListEntity maximum |
Cluster "Food Reorder" | 1 maximum | 1 ReorderEntity 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 Food (Alimentation) :
ProductEntity
StoreEntity
RecipeEntity
FoodShoppingCart
FoodShoppingList
FoodReorderCluster
Les tableaux ci-dessous décrivent les attributs disponibles pour chaque type et indiquent s'ils sont obligatoires.
ProductEntity
L'objet ProductEntity
représente un article individuel (tel qu'un article d'épicerie ou un plat proposé par un restaurant, ou encore une promotion) que les développeurs partenaires souhaitent publier.
Attribut | Obligatoire ? | Description | Format |
---|---|---|---|
Images poster | Obligatoire | Vous devez fournir au moins une image. | Consultez la section Caractéristiques des images pour en savoir plus. |
URI d'action | Obligatoire |
Lien profond vers la page de l'application affichant des informations sur le produit. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes |
URI |
Titre | Facultatif | Nom du produit. | Texte libre Taille de texte recommandée : 90 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Prix (actuel) | Obligatoire sous certaines conditions | Prix actuel du produit. À fournir si le prix barré est indiqué. |
Texte libre |
Prix (barré) | Facultatif | Prix d'origine de l'entité, qui sera barré dans l'UI. | Texte libre |
Accroche | Facultatif | Accroche qui met en avant une promotion, un événement ou une nouveauté pour le produit, le cas échéant. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Texte en petits caractères de l'accroche | Facultatif | Texte en petits caractères pour l'accroche. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Note (facultatif) – Remarque : Toutes les notes sont affichées selon notre système d'évaluation standard. | |||
Note (valeur maximale) | Facultatif | Valeur maximale de l'échelle d'évaluation. À fournir si la valeur de la note actuelle est également indiquée. |
Nombre >= 0.0 |
Note (valeur actuelle) | Facultatif | Valeur actuelle de l'échelle d'évaluation. À fournir si la valeur maximale de la note est également indiquée. |
Nombre >= 0.0 |
Nombre de notes | Facultatif | Nombre de notes pour le produit. Remarque : Indiquez ce champ si votre application contrôle la façon dont le nombre est affiché aux utilisateurs. Utilisez une chaîne concise. Par exemple, si le nombre est de 1 000 000, envisagez d'utiliser une abréviation telle que 1 M afin que le nombre ne soit pas tronqué pour les tailles d'affichage plus petites. |
Chaîne |
Note : valeur du nombre | Facultatif | Nombre de notes pour le produit. Remarque : Indiquez ce champ si vous ne gérez pas vous-même la logique d'affichage des abréviations. Si les valeurs "Nombre" et "Valeur du nombre" sont présentes, "Nombre" est affichée pour les utilisateurs. |
Longue |
DisplayTimeWindow : définissez la période d'affichage d'un contenu sur une surface (facultatif). | |||
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. |
Code temporel de l'epoch (en millisecondes) |
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. |
Code temporel de l'epoch (en millisecondes) |
StoreEntity
L'objet StoreEntity
représente un magasin individuel que les développeurs partenaires souhaitent publier, comme un restaurant ou une épicerie.
Attribut | Obligatoire ? | Description | Format |
---|---|---|---|
Images poster | Obligatoire | Vous devez fournir au moins une image. | Consultez la section Caractéristiques des images pour en savoir plus. |
URI d'action | Obligatoire | Lien profond vers la page de l'application affichant des informations sur le magasin. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes. |
URI |
Titre | Facultatif | Nom du magasin. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Position | Facultatif | Emplacement du magasin. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Accroche | Facultatif | Accroche qui met en avant une promotion, un événement ou une nouveauté pour le magasin, le cas échéant. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Texte en petits caractères de l'accroche | Facultatif | Texte en petits caractères pour l'accroche. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Description | Facultatif | Description du magasin. | Texte libre Taille de texte recommandée : 90 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Remarque : Toutes les notes sont affichées selon notre système d'évaluation standard. | |||
Note (valeur maximale) | Facultatif | Valeur maximale de l'échelle d'évaluation. À fournir si la valeur de la note actuelle est également indiquée. |
Nombre >= 0.0 |
Note (valeur actuelle) | Facultatif | Valeur actuelle de l'échelle d'évaluation. À fournir si la valeur maximale de la note est également indiquée. |
Nombre >= 0.0 |
Nombre de notes | Facultatif | Nombre de notes pour le magasin. Remarque : Indiquez ce champ si votre application souhaite contrôler la façon dont elle est présentée aux utilisateurs. Fournissez la chaîne concise qui peut être affichée pour l'utilisateur. Par exemple, si ce nombre est égal à 1 000 000, envisagez d'utiliser des abréviations telles que "1 M", afin qu'il ne soit pas tronqué sur les petits écrans. |
Chaîne |
Note : valeur du nombre | Facultatif | Nombre de notes pour le magasin. Remarque : Fournissez ce champ si vous ne souhaitez pas gérer vous-même la logique d'affichage des abréviations. Si les valeurs "Nombre" et "Valeur du nombre" sont présentes, nous utiliserons le nombre pour l'afficher aux utilisateurs. |
Longue |
RecipeEntity
L'objet RecipeEntity
représente un ingrédient que les partenaires de développement souhaitent publier.
Attribut | Obligatoire ? | Description | Format |
---|---|---|---|
Images poster | Obligatoire | Vous devez fournir au moins une image. | Consultez la section Caractéristiques des images pour en savoir plus. |
URI d'action | Obligatoire | Lien profond vers la page de l'application affichant des informations sur la recette. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes. |
URI |
Titre | Facultatif | Nom de la recette. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Auteur | Facultatif | Auteur de la recette. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Temps de cuisson/préparation | Facultatif | Temps de cuisson de la recette. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Accroche | Facultatif | Accroche qui met en avant une promotion, un événement ou une nouveauté pour la recette, le cas échéant. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Catégorie | Facultatif | Catégorie de la recette. | Texte libre Taille de texte recommandée : 45 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Description | Facultatif | Description de la recette. | Texte libre Taille de texte recommandée : 90 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Remarque : Toutes les notes sont affichées selon notre système d'évaluation standard. | |||
Note (valeur maximale) | Facultatif | Valeur maximale de l'échelle d'évaluation. À fournir si la valeur de la note actuelle est également indiquée. |
Nombre >= 0.0 |
Note (valeur actuelle) | Facultatif | Valeur actuelle de l'échelle d'évaluation. À fournir si la valeur maximale de la note est également indiquée. |
Nombre >= 0.0 |
Nombre de notes | Facultatif | Nombre de notes attribuées à la recette. Remarque : Indiquez ce champ si votre application souhaite contrôler la façon dont elle est présentée aux utilisateurs. Fournissez la chaîne concise qui peut être affichée pour l'utilisateur. Par exemple, si le nombre est de 1 000 000, envisagez d'utiliser des abréviations telles que 1 M afin qu'il ne soit pas tronqué sur les tailles d'écran plus petites. |
Chaîne |
Note : valeur du nombre | Facultatif | Nombre de notes pour la recette. Remarque:Renseignez ce champ si vous ne souhaitez pas gérer vous-même la logique d'abréviation d'affichage. Si les valeurs "Nombre" et "Valeur du nombre" sont présentes, nous utiliserons le nombre pour l'afficher aux utilisateurs. |
Longue |
FoodShoppingCart
Attribut | Obligatoire ? | Description | Format |
---|---|---|---|
URI d'action | Obligatoire |
Lien profond vers le panier dans l'application du partenaire. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes. |
URI |
Nombre d'articles | Obligatoire | Nombre d'articles dans le panier (et pas seulement le nombre de produits). Par exemple, s'il y a trois oranges et une pomme dans le panier, ce nombre doit être égal à 4. |
Entier >= 1 |
Titre | Facultatif | Titre du panier (par exemple, Votre panier). Si aucun titre n'est fourni par le développeur, Your cart (Votre panier) est utilisé par défaut. |
Texte libre Taille de texte recommandée : 25 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Texte de l'action | Facultatif |
Texte d'incitation à l'action du bouton du panier (par exemple, Votre panier). Si aucun texte d'incitation à l'action n'est fourni par le développeur, Afficher le panier est l'option par défaut. Cet attribut est compatible avec les versions 1.1.0 et ultérieures. |
Chaîne |
Images du panier | Facultatif | Images de chaque produit dans le panier. Jusqu'à 10 images peuvent être fournies par ordre de priorité. Le nombre réel d'images affichées dépend du facteur de forme de l'appareil. |
Consultez la section Caractéristiques des images pour en savoir plus. |
Étiquette des articles | Facultatif | Liste des étiquettes d'articles de la liste de courses. Le nombre réel d'étiquettes affichées dépend du facteur de forme de l'appareil. |
Liste d'étiquettes de texte libre Taille de texte recommandée : 20 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
DisplayTimeWindow : définissez la période d'affichage d'un contenu sur une surface (facultatif). | |||
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. |
Code temporel de l'epoch (en millisecondes) |
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. |
Code temporel de l'epoch (en millisecondes) |
FoodShoppingList
Attribut | Obligatoire ? | Description | Format |
---|---|---|---|
URI d'action | Obligatoire |
Lien profond vers la liste de courses dans l'application du partenaire. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes. |
URI |
Nombre d'articles | Obligatoire | Nombre d'articles dans la liste de courses. | Entier >= 1 |
Titre | Facultatif |
Titre de la liste (par exemple, Votre liste de courses). Si aucun titre n'est fourni par le développeur, Shopping list (Liste de courses) est utilisé par défaut. |
Texte libre Taille de texte recommandée : 25 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Étiquette des articles | Obligatoire | Liste des étiquettes d'articles de la liste de courses. Vous devez fournir au moins 1 étiquette et jusqu'à 10 étiquettes par ordre de priorité. Le nombre réel d'étiquettes affichées dépend du facteur de forme de l'appareil. |
Liste d'étiquettes de texte libre Taille de texte recommandée : 20 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
FoodReorderCluster
Attribut | Obligatoire ? | Description | Format |
---|---|---|---|
URI d'action | Obligatoire |
Lien profond permettant de réorganiser les articles dans l'application du partenaire. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes. |
URI |
Texte de l'action | Facultatif |
Texte d'incitation à l'action du bouton de réorganisation (par exemple, Commander à nouveau). Si aucun texte d'incitation à l'action n'est fourni par le développeur, Réorganiser est la valeur par défaut. Cet attribut est compatible avec les versions 1.1.0 et ultérieures. |
Chaîne |
Nombre d'articles | Obligatoire |
Nombre d'articles de la commande précédente (et pas seulement le nombre de produits). Par exemple, si la commande comprend 3 cafés simples et 1 croissant, ce nombre doit être 4. |
Entier >= 1 |
Titre | Obligatoire | Titre de l'article réorganisé. | Texte libre Taille de texte recommandée : 40 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Étiquette des articles | Facultatif (Si elles ne sont pas fournies, des images poster doivent l'être) |
Liste des étiquettes d'articles de la commande précédente. Vous pouvez fournir jusqu'à 10 étiquettes par ordre de priorité. Le nombre réel d'étiquettes affichées dépend du facteur de forme de l'appareil. |
Liste de texte libre Taille de texte recommandée par étiquette : 20 caractères maximum (si le texte est trop long, des points de suspension peuvent s'afficher) |
Images poster | Facultatif (Si ce n'est pas le cas, les étiquettes des articles doivent être fournies.) |
Images des articles de la commande précédente. Jusqu'à 10 images peuvent être fournies par ordre de priorité. Le nombre réel d'images affichées dépend du facteur de forme de l'appareil. |
Consultez la section Caractéristiques des images pour en savoir plus. |
Caractéristiques des images
Vous trouverez ci-dessous les spécifications requises pour les composants Image :
Format | Nombre minimal de pixels | Nombre de pixels recommandé |
---|---|---|
Carré (1x1) Préféré |
300 x 300 | 1 200 x 1 200 |
Paysage (1,91 x 1) | 600 x 314 | 1 200 x 628 |
Format portrait (4 x 5) | 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.
- Utilisez un arrière-plan transparent pour que l'image s'affiche correctement avec les paramètres du thème sombre et clair.
É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).
AppEngageFoodClient
permet la publication des clusters liés à l'alimentation.
Les API suivantes permettent de publier des clusters dans le client :
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishFoodShoppingCart
publishFoodShoppingList
publishReorderCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteFoodShoppingCartCluster
deleteFoodShoppingListCluster
deleteReorderCluster
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. } });
publishRecommendationClusters
Cette API permet de publier une liste d'objets RecommendationCluster
.
Un objet RecommendationCluster
peut avoir les attributs suivants :
Attribut | Obligatoire ? | Description |
---|---|---|
Liste des entités ProductEntity, StoreEntity ou RecipeEntity | Obligatoire | Liste des entités qui forment les recommandations de ce cluster "Recommendation". Les entités d'un cluster unique doivent être du même type. |
Titre | Obligatoire | Titre du cluster "Recommendation" (par exemple, Grande réduction sur le menu du Nouvel An). Taille de texte recommandée : 25 caractères maximum (si le texte est trop long, des points de suspension s'affichent) |
Sous-titre | Facultatif | Sous-titre du cluster "Recommandations". |
URI d'action | Facultatif |
Lien profond vers la page de l'application partenaire où les utilisateurs peuvent voir la liste complète des recommandations. Remarque : Vous pouvez utiliser des liens profonds pour l'attribution. Consultez ces questions fréquentes. |
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Big savings on Thanksgiving menu") .build()) .build())
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Big savings on Thanksgiving menu") .build()) .build());
Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :
- Toutes les données existantes du cluster "Recommendation" sont supprimées.
- Les données de la requête sont analysées et stockées dans de nouveaux clusters "Recommendation".
En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.
publishFeaturedCluster
Cette API permet de publier un objet FeaturedCluster
.
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.
publishFoodShoppingCart
Cette API permet de publier un objet FoodShoppingCart
.
Kotlin
client.publishFoodShoppingCart( PublishFoodShoppingCartClusterRequest.Builder() .setShoppingCart( FoodShoppingCart.Builder() ... .build()) .build())
Java
client.publishFoodShoppingCart( new PublishFoodShoppingCartClusterRequest.Builder() .setShoppingCart( new FoodShoppingCart.Builder() ... .build()) .build());
Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :
- Les données
FoodShoppingCart
existantes du développeur partenaire sont supprimées. - Les données de la requête sont analysées et stockées dans le cluster "Shopping Cart" mis à jour.
En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.
publishFoodShoppingList
Cette API permet de publier un objet FoodShoppingList
.
Kotlin
client.publishFoodShoppingList( PublishFoodShoppingListRequest.Builder() .setFoodShoppingList( FoodShoppingListEntity.Builder() ... .build()) .build())
Java
client.publishFoodShoppingList( new PublishFoodShoppingListRequest.Builder() .setFoodShoppingList( new FoodShoppingListEntity.Builder() ... .build()) .build());
Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :
- Les données
FoodShoppingList
existantes du développeur partenaire sont supprimées. - Les données de la requête sont analysées et stockées dans le cluster "Shopping List" mis à jour.
En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.
publishReorderCluster
Cette API permet de publier un objet FoodReorderCluster
.
Kotlin
client.publishReorderCluster( PublishReorderClusterRequest.Builder() .setReorderCluster( FoodReorderCluster.Builder() ... .build()) .build())
Java
client.publishReorderCluster( new PublishReorderClusterRequest.Builder() .setReorderCluster( new FoodReorderCluster.Builder() ... .build()) .build());
Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :
- Les données
FoodReorderCluster
existantes du développeur partenaire sont supprimées. - Les données de la requête sont analysées et stockées dans le cluster "Reorder" 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 |
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.
- Il aide les développeurs à fournir des informations sur 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".
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.
deleteFeaturedCluster
Cette API permet de supprimer le contenu du cluster "Featured".
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.
deleteFoodShoppingCartCluster
Cette API permet de supprimer le contenu du cluster "Food Shopping Cart".
Kotlin
client.deleteFoodShoppingCartCluster()
Java
client.deleteFoodShoppingCartCluster();
Lorsque le service reçoit la requête, il supprime les données existantes du cluster "Food Shopping Cart". En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.
deleteFoodShoppingListCluster
Cette API permet de supprimer le contenu du cluster "Food Shopping List".
Kotlin
client.deleteFoodShoppingListCluster()
Java
client.deleteFoodShoppingListCluster();
Lorsque le service reçoit la requête, il supprime les données existantes du cluster "Food Shopping List". En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.
deleteReorderCluster
Cette API permet de supprimer le contenu de "FoodReorderCluster".
Kotlin
client.deleteReorderCluster()
Java
client.deleteReorderCluster();
Lorsque le service reçoit la requête, il supprime les données existantes du cluster "Reorder". En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.
deleteUserManagementCluster
Cette API permet de supprimer le contenu du cluster "UserAccountManagement".
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.
deleteClusters
Cette API permet de supprimer le contenu d'un type de cluster donné.
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 | Nom de l'erreur | Remarque |
---|---|---|
1 |
SERVICE_NOT_FOUND |
Le service n'est pas disponible sur l'appareil donné. |
2 |
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é). |
3 |
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. |
4 |
SERVICE_CALL_PERMISSION_DENIED |
L'appelant n'est pas autorisé à effectuer l'appel du service. |
5 |
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é). |
6 |
SERVICE_CALL_INTERNAL |
Une erreur s'est produite au niveau du service. |
7 |
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 deContext.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 shopping cart cluster publish when PUBLISH_FOOD_SHOPPING_CART
// broadcast is received
// Trigger shopping list cluster publish when PUBLISH_FOOD_SHOPPING_LIST
// broadcast is received
// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
// received
}
public static void registerBroadcastReceivers(Context context) {
context = context.getApplicationContext();
// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));
// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));
// Register Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));
// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_LIST));
// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER));
}
- Déclarez une implémentation de manière statique avec la balise
<receiver>
dans le fichierAndroidManifest.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.food.PUBLISH_FOOD_SHOPPING_CART" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER" />
</intent-filter>
</receiver>
</application>
Les intents suivants sont envoyés par le service :
com.google.android.engage.action.PUBLISH_RECOMMENDATION
Nous vous recommandons de démarrer un appelpublishRecommendationClusters
lorsque vous recevez cet intent.com.google.android.engage.action.PUBLISH_FEATURED
Nous vous recommandons de démarrer un appelpublishFeaturedCluster
lors de la réception de cet intent.com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART
Nous vous recommandons de démarrer un appelpublishFoodShoppingCart
lors de la réception de cet intent.com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST
Nous vous recommandons de démarrer un appelpublishFoodShoppingList
lors de la réception de cet intent.com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER
Nous vous recommandons de démarrer un appelpublishReorderCluster
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
Contactez engage-developers@google.com 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 engage-developers@google.com 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), Shopping Cart (Panier), Shopping List (Liste de courses) et Reorder (Réorganiser) seront publiés et visibles par les utilisateurs.