Reviews & Ratings — Configuración por plataforma

Planes: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓ (la integración de reviews es agnóstica al plan; la plataforma/app subyacente es la que habilita la recogida de reviews)

Audiencia: merchants que quieren aggregateRating y review schema en sus productos (mejora rich results en SERP y señales de confianza para LLMs). También developers de Clione trabajando en el generador de schema y en el score de Pulse.

---

Por qué importa

aggregateRating y review de Schema.org en Product son las únicas señales que:

• Renderizan el widget de estrellas en la SERP de Google (impacto enorme en CTR).
• Son citadas explícitamente por crawlers LLM cuando los usuarios preguntan "¿es X bueno?".
• Suben el score de Pulse (10-15 puntos según el peso).

Sin ellas, el schema de Product carece de datos que los crawlers esperan. El score de Clione lo reflejará.

⚠️ Importante: activa los reviews PRIMERO en tu plataforma, luego en Clione

Clione NO crea reviews. Los lee de tu plataforma de e-commerce. Si tu plataforma no tiene reviews activados, no hay nada que extraer — y no inventaremos valores placeholder (Schema.org lo prohíbe explícitamente; Google lo marca como spam).

---

BigCommerce

Activar reviews

1. BC admin → Settings → Channels → Edit channel (p. ej. "Storefront") → Customer Reviews → activa Enable.
2. (Opcional) Configura la moderación: Settings → Customer Reviews → elige "Require approval before publishing" o "Auto-publish".
3. (Opcional) Configura emails de invitación: Marketing → Marketing Emails → Review request → activa y pon un delay (p. ej. 14 días tras compra).

Verificar que los reviews fluyen

En el admin de BC, abre cualquier producto → pestaña Reviews. Deberías poder añadir un review manual aquí (útil para testing).

Extraer hacia Clione

Una vez un producto tenga al menos un review en BC, el sync de Clione lo recogerá automáticamente en la siguiente ejecución. Para forzar un sync ahora:

• Dashboard Clione → tienda → Sync → Sync products → espera a que termine.
• Confirma abriendo el detalle del producto en Clione → comprueba que aggregateRating muestra un conteo de rating + media.

Providers de reviews de terceros

Si usas Yotpo, Judge.me, Stamped.io, Reviews.io, Okendo (populares en BC), normalmente exponen los reviews vía sus propios widgets y una API separada. El sync de BC de Clione lee solo los reviews nativos de BC. Si quieres los reviews de terceros en tu schema, dos opciones:

• Pide a tu review provider que escriba de vuelta en los reviews nativos de BC (la mayoría lo soporta — busca su setting "Sync to BigCommerce").
• Usa el markup de schema del propio provider (inyectan su propio JSON-LD vía su script de widget). No mezcles; elige una sola fuente de verdad.

---

Shopify

Activar reviews

Shopify retiró la app nativa "Product Reviews" en 2023. Necesitas una app de terceros. Las más comunes:

• Judge.me (tier gratis, el más fácil)
• Yotpo Product Reviews & UGC (tier gratis + de pago)
• Loox (de pago, reviews con foto)
• Stamped.io (tier gratis + de pago)
• Shopify Product Reviews (deprecada pero aún instalada en muchas tiendas; legacy)

Confirma que la app escribe metafields de Shopify

Clione lee los reviews desde metafields de producto de Shopify bajo el namespace reviews.* (la convención canónica que usan Judge.me, Yotpo, Loox, Stamped.io cuando están bien configurados). En concreto:

• reviews.rating_count → número de reviews
• reviews.rating → media (0-5)
• reviews.individual → array de objetos de review individuales (opcional)

Si tu review provider no escribe estos metafields, activa el setting "Schema/SEO integration" en la app del provider — todos lo tienen, a veces llamado "Rich Snippets" o "Microdata".

Extraer hacia Clione

Dashboard Clione → tienda → Sync → Sync products. Tras el sync, el aggregateRating del producto debería aparecer.

---

Cómo usa Clione los datos

Cuando la plataforma expone reviews, el generador de schema en packages/semantic-core/src/signals/jsonld.ts añade:

{
  "@type": "Product",
  // ... otros campos ...
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.7",
    "reviewCount": "143",
    "bestRating": "5",
    "worstRating": "1"
  },
  "review": [
    {
      "@type": "Review",
      "author": { "@type": "Person", "name": "Jane Doe" },
      "datePublished": "2026-04-12",
      "reviewRating": { "@type": "Rating", "ratingValue": "5" },
      "reviewBody": "Excellent quality, highly recommend."
    }
    // ... hasta 5 reviews más recientes
  ]
}

Reglas que seguimos:

• Solo emitimos si reviewCount >= 1. Nunca placeholders.
• El array review se limita a 5 más recientes (evitar inflar el payload JSON-LD).
• Los nombres de autores se sanean (sin emails, sin PII).

---

Cómo trata el score de Pulse a los reviews

Cuando los reviews no están activados en la plataforma, Pulse solía marcar "Product missing aggregateRating" / "Product missing review" como fallos, lo que limitaba el score por debajo de 100.

Tras la corrección de contextualización (tarea #41), el score:

• Detecta si la plataforma tiene reviews activados (vía el check Settings → Channels → Customer Reviews en BC, o vía la presencia de un metafield de app de review en Shopify).
• Si están desactivados, esos campos se marcan como N/A en el desglose de Pulse — neutral, no penalización.
• Si están activados pero vacíos, marcados como "feature enabled, no data yet" — sigue neutral.
• Si están activados con datos pero nuestro sync no los ha extraído, marcados como warning (problema de sync).
• Solo cuando están activados con datos Y los tenemos, se espera presencia y emisión; la ausencia es un fallo.

Así, una tienda pequeña sin reviews todavía puede puntuar 100 si todo lo demás está bien.

---

Ubicación del tip de onboarding (UI)

El dashboard debería mostrar un tip contextual en tres sitios:

1. Desglose de Pulse, junto a "Product missing aggregateRating" — mostrar "Habilita reviews en BC (Settings → Channels → Customer Reviews) o instala Judge.me en Shopify" con un enlace a este doc.
2. Página de detalle de producto en Clione, en la pestaña de schema — mismo mensaje.
3. Wizard de onboarding al conectar una tienda por primera vez — mostrar "Recomendamos habilitar reviews en tu plataforma para puntuación máxima". Enlace a este doc.

La tarea #TBD rastrea el trabajo de UI.

---

Comparación: review providers de un vistazo

Provider	Plataformas	Tier gratis	Escribe metafields reviews.* de Shopify	Integración Clione
BC native Reviews	BigCommerce	Built-in	N/A (nativo)	Automática en sync
Shopify Product Reviews	Shopify	Sí (legacy)	Sí	Automática en sync
Judge.me	Shopify	Sí	Sí (toggle "Rich Snippets" on)	Automática en sync
Yotpo Product Reviews	Shopify + BC	Sí (limitado)	Sí (toggle "Rich Snippets" on)	Automática en sync
Loox	Shopify	No (solo de pago)	Sí (toggle "SEO integration" on)	Automática en sync
Stamped.io	Shopify + BC	Sí	Sí (toggle "Schema markup" on)	Automática en sync
Okendo	Shopify + BC	No (de pago)	Sí	Automática en sync
Reviews.io	Shopify + BC	Sí (limitado)	Sí (bajo "Integrations → Schema")	Automática en sync

La mayoría de apps de terceros vienen por defecto en "Off" para la integración de metafield/schema. La primera acción tras instalar es siempre: abrir los ajustes de la app, encontrar "Rich Snippets" o "Schema markup" y activarlos. Sin ese toggle, Clione no tiene nada que extraer.

Resolución de problemas

aggregateRating falta en el JSON-LD del storefront incluso tras instalar y configurar la app de reviews — Tres sitios donde comprobar:

1. La app efectivamente escribió los metafields. Abre Shopify admin → producto → sección Metafields → busca reviews.rating_count. Si no está, la app no escribió — comprueba el toggle "Rich Snippets" o "Schema integration" de la app.
2. El sync de Clione los recogió. Abre el detalle del producto en Clione → pestaña Raw JSON → busca aggregateRating. Si no está, lanza un sync fresco.
3. El Schema Injector / Theme App Extension está activado. Sin él, el metafield existe pero no llega a la página. Consulta Schema Injector.

Un producto BC muestra 5 reviews en el admin de BC pero Clione dice 0 — Timing del sync. El sync de Clione lee reviews por producto en el recorrido del producto. Lanza un sync fresco; si sigue en 0 tras terminar el sync, el channel de BC puede estar filtrando los reviews. Comprueba Settings → Channels → Storefront → Customer Reviews — ¿está en "Auto-publish" o "Require approval"? Los reviews pendientes no cuentan.

Un producto Shopify muestra reviews en el widget de la app pero no en el JSON-LD de Clione — Casi siempre el toggle "Rich Snippets" en la app de reviews. Tras activarlo, dale a la app unos minutos para hacer backfill de los metafields, y luego lanza un sync fresco de Clione.

El conteo de reviews es correcto pero la media de rating está mal — Cada app calcula la media de forma ligeramente distinta (ponderada vs simple, reglas de redondeo). Clione usa el valor del metafield reviews.rating literal — arregla la discrepancia a nivel de la app de reviews.

El star rating no aparece en la SERP de Google aunque el JSON-LD sea correcto — Google tarda 4-12 semanas en mostrar estrellas en SERPs para productos nuevos, y nunca está garantizado. Usa el Rich Results Test de Google para confirmar que el markup es válido; la visibilidad en SERP es una decisión de ranking separada.

Pasos de instalación por plataforma para los providers más habituales

Judge.me (Shopify) — camino más rápido

1. Shopify App Store → instala Judge.me.
2. Dashboard de Judge.me → Settings → SEO → activa Rich Snippets.
3. (Opcional) Settings → Display → activa Show ratings on collection pages para renderizar el iconito de estrellas en grids de catálogo.
4. Espera ~5 minutos para que Judge.me haga backfill de metafields en los reviews existentes.
5. En Clione, ejecuta Store → Sync → Products para extraer los metafields.

Yotpo (Shopify) — paso extra

1. Shopify App Store → instala Yotpo Reviews.
2. Dashboard de Yotpo → Apps → activa Rich Snippets.
3. Apps → activa Product Metafields Sync (específico de Yotpo — sin él, solo estrellas renderizadas por el widget; sin metafields).
4. Espera al sync.
5. En Clione, Store → Sync → Products.

Stamped.io (Shopify o BC)

1. Instala vía app store.
2. Dashboard de Stamped → Settings → Display Settings → SEO → activa Rich Snippets / Schema Markup.
3. Settings → Product Reviews → Integrations → activa "Sync to Shopify metafields" (Shopify) o "Sync to BC native reviews" (BC).
4. Espera al sync.
5. En Clione, Store → Sync → Products.

Loox (Shopify)

1. Instala desde el app store (de pago).
2. Dashboard de Loox → Settings → Schema markup → activa.
3. Espera al sync.
4. Sync de Clione.

Por qué no fabricamos ratings

La FAQ de merchant que recibimos más a menudo es "¿puede Clione generar ratings placeholder?". La respuesta es no, y no va a cambiar:

• La documentación de Rich Results de Google prohíbe explícitamente ratings placeholder o auto-generados.
• Los ratings falsos detectados acaban en penalizaciones manuales (rich results suprimidos, a veces una penalización de ranking en búsqueda).
• Los crawlers LLM cada vez sospechan más de ratings no verificados y pueden despriorizarlos igualmente.
• Es malo para los compradores — un rating de 4.7 estrellas sin reviews que lo respalden es más dañino que ningún rating cuando los compradores lo descubren.

El camino correcto es recoger reviews reales. Si tu tienda aún no tiene reviews, usa los proxies LLM-friendly que Clione sí genera (reasoning, recommended_for, decision_logic) en su lugar — no pretenden ser validación de terceros.

Relacionado

• docs/SIGNALS.md — qué señales generamos por tipo de entidad.
• docs/PULSE_SCORING.md — cómo se pondera el score.
• packages/semantic-core/src/signals/jsonld.ts — generador de schema (bloque review/aggregateRating).
• Tarea #41 — contextualizar el Pulse score (no penalizar por funcionalidades no disponibles).