Chaque entité abonnée à la fonctionnalité Génération d'avis obtient une page de collecte d'avis standard qui ne peut être personnalisée. Si vous souhaitez bénéficier d'un contrôle total sur l'apparence, l'ergonomie et les données supplémentaires recueillies sur votre expérience de collecte, créez une page de collecte personnalisée à l'aide de l'API Envoi d'avis. Cet article explique le fonctionnement de l'API et les options à prendre en compte lors de la création de vos pages.

Comment les auteurs d'avis accèdent aux pages de collecte

• Sur invitation : une entreprise envoie directement au client une invitation avec un lien.
• Sans invitation : une entreprise publie une page de collecte standard et accessible au public à laquelle les clients peuvent accéder d'eux-mêmes.

Structures de page de collecte courantes

• Une page par entité : la structure la plus courante, avec une page de collecte unique pour chaque entité pour laquelle vous souhaitez des avis. Une entreprise avec 100 produits, par exemple, aurait une page par produit.
• Une page avec un sélecteur d'entités : une seule page pour plusieurs entités, sur laquelle l'auteur choisit l'entité pour laquelle il souhaite laisser un avis. La page inclut l'entité sélectionnée dans sa requête API. Une entreprise peut utiliser une seule page pour une catégorie entière de produits avec un sélecteur pour choisir le produit précis.
• Une page regroupant plusieurs entités : une seule page collecte les avis pour plusieurs entités au cours de la même session. Par exemple, une entreprise disposant d'entités distinctes « Assurance auto – Garanties » et « Assurance auto – Service » peut permettre à un client de donner son avis sur les deux à partir d'un seul formulaire.

Planifier votre mise en œuvre

Avant de passer à la conception, demandez-vous :

• Quelles entités ont besoin d'une page de collecte et si vous avez besoin d'un modèle de formulaire unique ou de plusieurs selon le type d'entité.
• Quelles expériences vous souhaitez : uniquement la création d'avis, ou aussi la mise à jour et la suppression des avis.
• Si vous envisagez de collecter des attributs supplémentaires au-delà des champs d'avis standard.

Le design vous appartient entièrement. La seule condition requise est que votre page puisse envoyer des requêtes aux points de terminaison d'envoi des avis pour valider un avis, et éventuellement pour en mettre à jour ou en supprimer.

Exigences pour les avis

Les avis collectés via votre page doivent être conformes à l'objet d'avis Yext : une note moyenne de 1 à 5 étoiles, le texte de l'avis et les informations sur l'auteur. L'objet d'avis ne prend pas en charge les sous-notes ni les champs personnalisés pour des attributs supplémentaires concernant l'auteur de l'avis, mais vous pouvez associer des intitulés d'avis à un avis validé. Consultez la documentation de l'API pour obtenir la référence complète de l'objet d'avis.

Prévenir le spam

Créer une page de collecte personnalisée implique d'exposer une clé API côté client, ce qui permet à toute personne qui la trouve de laisser des avis directement sur votre compte. Actuellement, Yext ne propose pas de prise en charge CAPTCHA intégrée pour ces demandes. Si vous souhaitez vérifier que les avis proviennent de véritables utilisateurs, ajoutez une solution CAPTCHA (telle que Google reCAPTCHA ou hCaptcha) avec un serveur proxy entre votre page de collection et l'API Yext. Le proxy valide la réponse CAPTCHA, puis transmet les requêtes validées à Yext.

Points de terminaison de l'API Envoi d'avis

Configurer l'accès à l'API

Créez une application dans la console développeur et accordez-lui l'accès à l'API Content Delivery Envoi d'avis, qui couvre la création, la mise à jour et la suppression des avis. Étant donné que cette clé API est exposée côté client, limitez la portée de l'application à cette seule autorisation.

Créer un avis

Collectez les champs requis sur votre page, généralement via un formulaire, et soumettez-les au point de terminaison Review Submission: Create lorsque l'utilisateur laisse un avis.

Gérer la réponse de l'API

Le point de terminaison Create ne crée pas l'avis de manière synchrone, donc il ne peut pas renvoyer un ID d'avis immédiatement. Une requête réussie renvoie une réponse 202 Accepted ainsi qu'un apiIdentifier correspondant soit à la valeur invitationUid transmise dans la requête, soit à un UUID généré automatiquement si vous n'en avez pas fourni. Cette valeur correspond de manière unique à l'avis créé et est requise pour le mettre à jour ou le supprimer ultérieurement. Une requête présentant des problèmes de validation, comme une adresse e-mail non valide, renvoie une erreur 400 que votre page peut afficher sur l'écran de l'utilisateur.

Prise en charge de la mise à jour et de la suppression des avis

Permettez aux utilisateurs finaux de mettre à jour ou de supprimer leurs propres avis. Deux scénarios reviennent le plus souvent :

• L'utilisateur souhaite corriger une erreur ou il a changé d'avis juste après avoir validé son envoi.
• L'entreprise répond à un avis et la solution apportée incite l'utilisateur final à mettre à jour ou à supprimer son avis initial, parfois longtemps après sa publication.

Ces deux scénarios nécessitent des approches différentes.

Mises à jour immédiates

Comme un avis envoyé via Review Submission: Create n'est pas immédiatement disponible via Review: Get ou Review: List, permettez les mises à jour immédiates en stockant le contenu de l'avis et la valeur apiIdentifier renvoyée côté client. Toute demande de mise à jour ou de suppression déclenchée par l'utilisateur juste après l'envoi peut réutiliser cette valeur stockée.

Mises à jour non immédiates

Pour prendre en charge les modifications après que l'utilisateur a quitté la page, récupérez l'avis ultérieurement en utilisant l'API Streams plutôt que de compter sur les données stockées côté client. Filtrez votre requête à l'API Streams sur le champ apiIdentifier pour récupérer l'avis correspondant, puis affichez une interface de modification avec ces données. Veuillez noter que l'avis en question doit avoir le statut LIVE (Publié) pour pouvoir être renvoyé par l'API Streams. Si l'avis est toujours QUARANTINED (En quarantaine), il ne sera pas renvoyé par l'API Streams.

Deux exemples illustrent les cas où cela peut se produire :

• Notifier l'auteur d'un avis d'une réponse : surveillez les événements webhook REVIEW_COMMENT_UPDATED. Lorsqu'une entreprise répond à un avis de première main, envoyez à l'auteur un e-mail contenant un lien vers la page de collecte avec la valeur apiIdentifier comme paramètre de requête. Lorsque l'auteur clique dessus, la page récupère l'avis via apiIdentifier et affiche l'interface de modification.
• Revenir via le lien d'invitation d'origine : si un utilisateur clique à nouveau sur le lien contenu dans l'e-mail d'invitation initial après avoir déjà laissé un avis, la page reçoit la même valeur invitationUid en tant que paramètre de requête. Comme apiIdentifier est égal à invitationUid chaque fois qu'une invitation a été utilisée pour créer l'avis, récupérez l'avis en utilisant cette valeur. Si un avis correspondant existe, affichez l'interface de modification ; sinon, affichez l'expérience de création standard.

La valeur apiIdentifier d'un avis est un UUID généré plutôt qu'un identifiant d'avis séquentiel, ce qui renforce la sécurité dans ce cas d'utilisation : avec un identifiant séquentiel, il suffirait à un utilisateur de modifier une valeur connue à la hausse ou à la baisse pour accéder à d'autres avis.

Récupérer les avis via l'API Streams

L'API Streams est une API à faible latence et personnalisable, adaptée à la récupération des avis côté client. Yext fournit une application préconfigurée pour ce cas d'utilisation, qui crée un point de terminaison Streams avec l'ID reviewsStreamsEndpoints_reviews. Vous n'avez donc pas besoin de configurer l'indexation manuellement. Voici un exemple de requête :