Documentación para desarrolladores de Reseñas

Las reseñas son modelos estructurados para recopilar, moderar y representar comentarios públicos en FaceFlow.

Permiten a los equipos técnicos gestionar contenido sensible para la reputación como salida del sitio gobernada en lugar de testimonios libres no gestionados.

Responsabilidad principal

Un modelo de reseña es responsable de:

• modelos de reseña configurables
• campos de calificación estructurados
• captura pública de envíos
• política de moderación y verificación
• salida de visualización embebible
• control de publicación

Esto hace que las reseñas sean adecuadas para secciones del sitio web orientadas a la confianza que necesitan tanto visibilidad pública como control operativo.

Modelo de reseña principal

Un modelo de reseña normalmente combina:

• campos de identidad centrales de la reseña
• campos de calificación
• dimensiones de calificación personalizadas opcionales
• ajustes de moderación
• comportamiento de verificación
• configuración de presentación y salida

En la práctica, la capa de reseñas define tanto qué comentarios se pueden recopilar como qué comentarios aprobados se pueden publicar de nuevo en el sitio web.

Conceptualmente:

{
  "name": "customer-success-reviews",
  "fields": [
    { "name": "author_name", "type": "text", "required": true },
    { "name": "rating", "type": "rating", "required": true },
    { "name": "review_title", "type": "text", "required": true },
    { "name": "review_content", "type": "textarea", "required": true }
  ],
  "settings": {
    "moderation": "required",
    "verification": "optional"
  }
}

Flujo de envío y publicación

A grandes rasgos:

1. se define un modelo de reseña de forma central
2. se incrusta en una Página mediante un Componente
3. los visitantes envían comentarios
4. se aplican reglas de moderación y verificación
5. las entradas aprobadas se representan de nuevo en la experiencia del sitio web

Conceptualmente:

review widget render
  -> visitor submission
  -> pending review state
  -> moderation / verification
  -> approved review published

Por eso las reseñas deben tratarse como contenido público gobernado, no simplemente otro formulario de entrada.

Estructura de calificación

Los modelos de reseña pueden admitir:

• calificación general
• título de la reseña
• contenido de la reseña
• dimensiones de calificación personalizadas para comentarios más estructurados

Ejemplo:

overall_rating
service_rating
communication_rating
value_rating

Use dimensiones adicionales solo cuando mejoren la confianza y la interpretación.

Ejemplo de modelo de reseña

Un revisor técnico debe poder inspeccionar claramente la forma del modelo:

{
  "name": "service-review",
  "fields": [
    { "name": "author_name", "type": "text", "required": true },
    { "name": "rating", "type": "rating", "required": true },
    { "name": "review_title", "type": "text", "required": true },
    { "name": "review_content", "type": "textarea", "required": true }
  ],
  "settings": {
    "moderation": "required",
    "verification": "optional"
  }
}

Esto ayuda a los equipos a revisar lo que se está recopilando, qué es obligatorio y cuánto esfuerzo de moderación probablemente generará el modelo.

Moderación y verificación

La moderación y la verificación son centrales en el diseño de reseñas.

Los equipos técnicos deben decidir:

• si las entradas requieren aprobación
• si se necesita verificación adicional
• quién es responsable de las decisiones de publicación
• cómo se debe manejar el contenido sensible para la reputación

Cuanto mayor sea el riesgo para la reputación, más fuertes suelen ser los controles.

Incrustar reseñas

Las reseñas suelen incrustarse en secciones de la página mediante Componentes.

Un marcador de incrustación común es:

<div data-review-embed="service-review"></div>

Sección de ejemplo:

<section class="customer-proof">
  <header>
    <h2>What customers say</h2>
  </header>
  <div data-review-embed="customer-success-reviews"></div>
</section>

Esto mantiene la recopilación y la visualización de reseñas reutilizables mientras permite a la Página colocar contenido de confianza donde tenga mayor impacto.

Incrustaciones fijas vs basadas en campos

Hay dos patrones de incrustación comunes.

Use un id de modelo de reseña gestionado fijo cuando la plantilla deba renderizar siempre un modelo de reseña específico:

<div data-review-embed="customer-success-reviews"></div>

Use una incrustación basada en campo cuando un Componente exponga un campo reviewSelect y los autores deban elegir el modelo de Reseña gestionado en el momento de la autoría:

<div data-review-embed="{serviceReview}"></div>

Regla de decisión:

• incrustación fija -> un flujo de confianza estable propiedad de la plantilla
• incrustación basada en campo -> Componente reutilizable con flujo de reseñas seleccionable por el autor

Patrón de integración

La ruta de ejecución limpia es:

Review model
-> Component embed via reviewSelect or explicit data-review-embed marker
-> Page composition
-> public submission, moderation, and approved display output

Eso mantiene la lógica del flujo de trabajo sensible a la reputación centralizada en lugar de dispersarla en marcados puntuales de la página.

Guía operativa

Un buen diseño de reseñas suele favorecer:

• un modelo de reseña por contexto de negocio
• propiedad clara de la moderación
• dimensiones de calificación estructuradas solo donde aporten valor real
• una experiencia de envío lo suficientemente corta para preservar la calidad
• un modelo de publicación que favorezca la confianza en lugar del ruido

Si un modelo de reseña se vuelve demasiado amplio, la calidad y la moderación suelen ser más difíciles de gestionar.

Guía sobre el contrato de calificación

Mantenga el modelo de calificación proporcional al flujo público.

Patrones típicos:

• sección de confianza simple -> calificación general + título + cuerpo de la reseña
• flujo de calidad de servicio -> calificación general más un pequeño número de dimensiones como servicio, comunicación o valor

Si un flujo público corto necesita demasiadas entradas de calificación, la calidad del envío y la tasa de finalización suelen disminuir.

Guía técnica

• separe los modelos de reseña por contexto de negocio
• alinee la política de moderación y verificación con la sensibilidad reputacional
• mantenga la recopilación pública de reseñas lo suficientemente breve para mantener la calidad de los envíos
• trate el contenido de reseñas publicado como salida gobernada
• considere la recopilación, moderación y visualización como un solo flujo de trabajo

Anti-patrones

Evite:

• un único modelo de reseña gigante usado para contextos de negocio no relacionados
• demasiadas dimensiones de calificación para un flujo público corto
• publicar sin una propiedad clara de la moderación
• tratar las reseñas como testimonios no gestionados pegados en Componentes
• diseñar el flujo de entrada sin revisar el modelo de visualización y aprobación

Ejemplo de patrón de construcción

Review model:
  customer-success-reviews

Component:
  review-strip

Embed:
  <div data-review-embed="customer-success-reviews"></div>

Ese patrón mantiene el contenido de confianza reutilizable y gobernado.

Relacionado

• Descripción general del producto de Reseñas
• Guía de Reseñas
• Componentes
• Páginas
• Usuarios