Cada entidad suscrita a Generación de comentarios recibe una página de recopilación de comentarios estándar y no personalizable. Si quiere tener control total sobre el aspecto, la experiencia del usuario y los datos adicionales que se recopilan en tu proceso de recopilación, cree una página de recopilación personalizada utilizando la API de envío de comentarios. Este artículo explica cómo funciona la API y las opciones a tener en cuenta a la hora de crear sus páginas.
Cómo acceden los revisores a las páginas de recopilación
- Por invitación: una empresa envía una invitación con un enlace directamente a un cliente.
- Sin una invitación: una empresa publica una página de recopilación estándar y de acceso público a la que los clientes pueden acceder por su cuenta.
Estructuras comunes de páginas de recopilación
- Una página por entidad: la estructura más común, con una única página de recopilación para cada entidad para la que desee comentarios. Una empresa con 100 productos, por ejemplo, tendría una página por producto.
- Una página con un selector de entidades: una sola página sirve para varias entidades, y el revisor selecciona la entidad que quiere revisar. La página incluye la entidad seleccionada en su solicitud de API. Una empresa puede utilizar una página para toda una categoría de productos, con un selector para el producto específico.
- Una página que recopila múltiples entidades: una sola página recopila comentarios para más de una entidad en la misma sesión. Por ejemplo, una empresa que cuente con entidades independientes denominadas «Seguro de automóvil - Cobertura» y «Seguro de automóvil - Servicio» podría permitir que un cliente valorara ambas desde un único formulario.
Planifique su implementación
Antes de empezar a crear, tenga en cuenta:
- Qué entidades requieren una página de recopilación y si necesita una plantilla de formulario o varias, según el tipo de entidad.
- ¿Qué operaciones desea admitir: solo la creación de comentarios, o también la modificación y la eliminación?
- Si tiene previsto recopilar datos adicionales, además de los campos estándares de comentario.
El diseño depende totalmente de usted. El único requisito es que su página pueda hacer solicitudes a los puntos finales de Envío de comentario para enviar un comentario y, opcionalmente, actualizarlo o eliminarlo.
Requisitos de comentarios
Los comentarios recogidos a través de su página deben ajustarse al objeto de comentario de Yext: una valoración de 1 a 5 estrellas, texto del comentario e información del autor. El objeto de comentario no admite subvaloraciones ni campos personalizados para otros atributos del revisor, pero puede adjuntar las etiquetas de comentario a un comentario enviado. Consulte la documentación de la API para ver la referencia completa del objeto de comentario.
Prevención del spam
Crear una página de recopilación personalizada implica exponer una clave de API en el lado del cliente, lo que permite que cualquier persona que la encuentre envíe comentarios directamente a su cuenta. Actualmente, Yext no ofrece compatibilidad integrada con CAPTCHA para estas solicitudes. Si desea verificar que los envíos provienen de usuarios reales, añada una solución CAPTCHA, como Google reCAPTCHA o hCaptcha, con un servidor proxy entre su página de colección y la API de Yext. El proxy valida la respuesta CAPTCHA, y luego reenvía las solicitudes verificadas a Yext.
Puntos finales de la API de envío de comentario
| Punto final | Descripción | URL |
|---|---|---|
| Envío de comentario: Create | Crea un comentario en primera persona nuevo. | POST https://cdn.yextapis.com/v2/accounts/{accountId}/reviewSubmission |
| Envío de comentario: Update | Actualiza un comentario en primera persona existente. | PUT https://cdn.yextapis.com/v2/accounts/{accountId}/reviewSubmission/{apiIdentifier} |
| Envío de comentario: Delete | Establece el estado de un comentario en primera persona existente a REMOVED.
|
DELETE https://cdn.yextapis.com/v2/accounts/{accountId}/reviewsSubmission/{apiIdentifier} |
Configurar el acceso a la API
Cree una aplicación en la consola de desarrolladores y concédale acceso a la API de revisión de entrega de contenido de envío de comentario, que incluye creación, actualización y eliminación. Dado que esta clave API está expuesta en el lado del cliente, solo se puede asignar este permiso a la aplicación.
Crear un comentario
Recopile los campos necesarios en la página, normalmente a través de un formulario, y envíelos al punto final Revisión de comentario: Create cuando el usuario haga un envío.
Gestionar la respuesta de la API
El punto final Crear no crea el comentario de forma sincrónica, por lo que no puede devolver un ID de comentario de inmediato. Una solicitud correcta devuelve una respuesta 202 Accepted junto con un apiIdentifier, que puede ser el invitationUid que proporcionó en la solicitud o un UUID generado recientemente si no proporcionó ninguno. Este valor corresponde 1:1 al comentario resultante y es necesario para actualizarlo o eliminarlo más adelante. Una solicitud con problemas de validación, como una dirección de correo electrónico inválida, devuelve un error 400 que su página puede mostrar al usuario.
Compatibilidad de la actualización y eliminación de comentarios
Permita que los usuarios finales actualicen o eliminen sus propios comentarios. La mayoría de las veces se presentan dos casos:
- El usuario quiere corregir un error o cambiar de opinión inmediatamente después de enviarlo.
- La empresa responde a un comentario, y la respuesta lleva al usuario final a actualizar o eliminar su comentario original, a veces mucho tiempo después de haberlo enviado.
Estos dos escenarios requieren enfoques diferentes.
Actualizaciones inmediatas
Dado que un comentario enviado a través de Revisar envío: Create no está disponible de inmediato a través de Comentario: Get o Comentario: List, permita actualizaciones inmediatas almacenando el contenido del comentario y el apiIdentifier devuelto en el lado del cliente. Cualquier solicitud de actualización o eliminación que el usuario active justo después de enviarla puede reutilizar ese valor almacenado.
Actualizaciones no inmediatas
Para admitir ediciones después de que el usuario haya abandonado la página, se debe obtener el comentario más tarde utilizando la API de Streams en lugar de depender de los datos almacenados en el lado del cliente. Filtre su solicitud de API de Streams en el campo apiIdentifier para recuperar el comentario correspondiente, luego muestre una experiencia de edición con esos datos. Tenga en cuenta que el comentario en cuestión deberá tener el estado PUBLICADO para que la API de Streams lo devuelva. Si el comentario sigue en CUARENTENA, la API de Streams no lo devolverá.
Dos ejemplos ilustran cuándo surge esta situación:
-
Notificar a un revisor de una respuesta: preste atención a los eventos de webhook
REVIEW_COMMENT_UPDATED. Cuando una empresa responde a una comentario de primera parte, envíe al revisor un enlace a la página de la colección con elapiIdentifiercomo parámetro de consulta. Cuando hacen clic, la página recupera el comentario medianteapiIdentifiery muestra la experiencia de edición. -
Volviendo a través del enlace de invitación original: si un usuario hace clic en su correo electrónico de invitación original nuevamente después de haber dejado un comentario, la página recibe el mismo
invitationUidcomo parámetro de consulta. Dado queapiIdentifieres igual ainvitationUidsiempre que se use una invitación para crear el comentario, obtenga el comentario utilizando ese valor. Si existe un comentario coincidente, se mostrará la experiencia de edición; de lo contrario, se mostrará la experiencia de creación estándar.
El apiIdentifier de un comentario es un UUID generado en lugar de un ID incremental de comentario, que es más seguro para este propósito: un ID incremental permitiría a cualquiera incrementar o reducir un valor conocido para acceder a otros comentarios.
Obtener comentarios a través de la API de Streams
La API Streams es personalizable y de baja latencia, y es adecuada para obtener comentarios desde el lado del cliente. Yext ofrece una aplicación preconfigurada para este caso de uso que crea un punto final de Streams con el ID reviewsStreamsEndpoints_reviews, así que no es necesario configurar la indexación manualmente. Una solicitud de ejemplo se presenta así: