Saltar al contenido principal

Instala el widget de FAQ en tu storefront

El widget de FAQ de Clione es una sola etiqueta <script> que inyecta:

  1. Un acordeón HTML visible de FAQs en la página, para que los compradores puedan leerlas.
  2. Un bloque JSON-LD FAQPage invisible en el <head> de la página, para que los motores de búsqueda y los crawlers de IA puedan indexarlas.

El widget auto-detecta la entidad actual (producto, categoría, página) y trae las FAQs correctas de Clione — incluyendo cualquier FAQ global que hayas definido (envíos, devoluciones, garantía).

Para autorar FAQs, mira Editor de FAQ. Esta página trata solo sobre instalar el widget en el storefront una vez existen las FAQs.

Antes de instalar​

  1. Necesitas una API key con scope products:read y al menos un dominio permitido en la lista blanca. Genérala en Store → Settings → API Keys (ver Editor de FAQ).
  2. Decide en qué parte de la página debería aparecer el acordeón de FAQ. La mayoría de tiendas lo ponen justo debajo de la descripción del producto, encima de productos relacionados.
  3. Con plan asignado: la funcionalidad de FAQ está disponible en Growth y superiores. Las cuentas Starter pueden enriquecer y propagar, pero no pueden usar el editor de FAQ ni el widget.

BigCommerce — Stencil (storefront clásico)​

Opción A — Editar tu tema​

  1. Admin de BigCommerce → Storefront → Themes → pulsa Advanced → Edit theme files en tu tema activo.
  2. Abre templates/components/products/product-view.html (la ruta varía ligeramente por tema — busca {{description}} para encontrar el bloque de descripción del producto).
  3. Pega el snippet justo después del bloque de descripción:
<div id="clione-faq"></div>
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-target="#clione-faq"
  async
></script>
  1. Pulsa Save arriba a la derecha. Stencil reconstruye el tema. El widget aparece en cada página de producto en ~30 segundos.

Para páginas de categoría: abre templates/pages/category.html y añade el mismo snippet. El widget auto-detecta el contexto de categoría.

Opción B — Usar el Script Manager de BC (sin editar el tema)​

Útil si no quieres tocar el tema pero aceptas que el widget aparezca en una ubicación fija (normalmente el pie de página).

  1. Admin de BigCommerce → Storefront → Script Manager → Create a Script.
  2. Name: Clione FAQ widget.
  3. Description: Renders FAQ accordion + FAQPage JSON-LD.
  4. Location on page: Footer.
  5. Select pages where script will be added: Storefront pages → elige Product pages (y Category pages si quieres).
  6. Script type: Script.
  7. Script contents:
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-target=".productView, .category"
  async
></script>
  1. Guarda.

El selector CSS de data-target le dice al widget dónde inyectar el acordeón. .productView funciona para la mayoría de temas Stencil en páginas de producto; .category para páginas de categoría.

Verificar​

  1. Abre cualquier página de producto enriquecido en incógnito.
  2. Baja hasta encontrar el acordeón de FAQ debajo de la descripción.
  3. Ver código fuente (Ctrl/Cmd + U) y busca FAQPage — deberías ver el bloque JSON-LD.
  4. Si el acordeón no apareció, revisa la consola del navegador en busca de errores (lo más habitual: API key no permitida para este dominio — mira Solución de problemas).

BigCommerce — headless / Catalyst​

Igual que el Schema Injector: renderiza server-side desde tu frontend. Usa la FAQ API directamente:

const res = await fetch(`https://api.clione.ai/api/v1/public/faq/render?entityType=product&entityId=${productId}`, {
  headers: { 'x-api-key': process.env.CLIONE_API_KEY },
})
const { htmlBlock, jsonLd } = await res.json()
// htmlBlock → renderiza en tu página de producto
// jsonLd → renderiza en <head>

Mira FAQ API para la spec completa.

Shopify — Online Store (temas Liquid)​

Opción A — Editar tu tema​

  1. Admin de Shopify → Online Store → Themes → en tu tema activo, pulsa el menú de tres puntos → Edit code.
  2. Abre sections/main-product.liquid (o templates/product.liquid en temas más antiguos).
  3. Localiza el bloque de descripción del producto (busca {{ product.description }}).
  4. Pega el snippet justo después:
<div id="clione-faq"></div>
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-target="#clione-faq"
  async
></script>
  1. Pulsa Save. El widget aparece en cada página de producto de inmediato.

Para páginas de colección: abre sections/main-collection-product-grid.liquid (o similar) y pega el mismo snippet. Para páginas de contenido: sections/main-page.liquid.

Opción B — Usar el editor de tema (sin código)​

Si tu tema soporta bloques HTML personalizados (Dawn sí, la mayoría de temas de pago sí):

  1. Editor de tema → abre una plantilla de producto → Add block → Custom Liquid (o Custom HTML).
  2. Pega el snippet de arriba.
  3. Save.

El widget aparece donde quiera que esté colocado el bloque en el orden de la sección. Puedes arrastrarlo arriba/abajo para posicionarlo encima o debajo de productos relacionados.

Verificar​

  1. Abre cualquier página de producto enriquecido en incógnito.
  2. El acordeón de FAQ debería aparecer en el hueco que elegiste.
  3. Ver código fuente y busca el JSON-LD FAQPage.

Notas para Shopify​

  • El widget de FAQ es independiente del theme app block de Clione. El app block gestiona el JSON-LD de Product; el widget de FAQ gestiona el JSON-LD de FAQPage. Ambos pueden estar activos sin conflicto.
  • El widget inyecta su acordeón en el DOM vía JavaScript, así que los crawlers server-rendered (Googlebot ahora ejecuta JS, los crawlers viejos no) no verán el texto del acordeón. SÍ verán el JSON-LD de FAQPage porque el widget lo inserta en <head> antes de cualquier first paint — pero si necesitas texto de FAQ server-rendered, cambia a la FAQ API y renderiza en Liquid tú mismo.

Shopify — Hydrogen / headless​

Igual que BigCommerce headless. Usa la FAQ API directamente desde el loader de ruta de Hydrogen y renderiza tanto el HTML del acordeón como el JSON-LD en tu componente.

Común a ambas plataformas​

Dominios permitidos​

La API key valida el header Origin de la petición contra la lista Allowed Domains que configuraste al generar la key. Si el widget intenta cargar en un dominio que no está en la lista, la API devuelve 403 y no se renderiza nada.

  • Para producción: lista tu dominio real del storefront (shop.example.com o example.com).
  • Para staging: incluye el dominio de staging (staging.shop.example.com) o usa wildcards (*.example.com).
  • Para pruebas locales: añade localhost y 127.0.0.1.

Actualiza la lista blanca en cualquier momento en Store → Settings → API Keys → Edit domains en la fila de la key.

Badge "Powered by Clione"​

El widget muestra un pequeño badge Powered by Clione en la parte inferior del acordeón por defecto.

  • En planes Growth, Pro y Agency puedes ocultar el badge desde Org → Settings → Branding.
  • En Starter y durante el trial, el badge está forzado y el toggle está deshabilitado. Está documentado en nuestros Términos de Servicio.

Auto-detección de la entidad actual​

El widget intenta la detección en este orden:

  1. Override explícito en la etiqueta script (data-entity-type + data-entity-id) — úsalo si tu plataforma no expone URLs o OG tags reconocibles.
  2. Meta tags OpenGraph — <meta property="og:type" content="product"> + <meta property="product:retailer_item_id" content="...">.
  3. Patrones de URL — Shopify /products/<handle>, BigCommerce /product/<slug>, clase de body en WooCommerce, etc.

Si la detección falla, el widget recurre a mostrar solo FAQs globales (envíos, devoluciones, etc.) y se salta las específicas de entidad. Para forzar la detección de entidad en un tema personalizado, usa el override explícito:

<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-target="#clione-faq"
  data-entity-type="product"
  data-entity-id="{{ product.id }}"
  async
></script>

(Sustituye {{ product.id }} por la sintaxis de plantilla que use tu plataforma.)

Solución de problemas​

"403 Forbidden" en la consola del navegador — El dominio de la página actual no está en la lista de dominios permitidos de la API key. Actualiza la lista en Store → Settings → API Keys.

El acordeón aparece pero el JSON-LD no — Race condition. El JSON-LD se añade al <head> ligeramente después del first paint en conexiones lentas. Recarga y revisa otra vez.

El acordeón está vacío para algunos productos pero lleno para otros — Los vacíos no tienen FAQs asignadas. Abre el producto en Clione → pestaña FAQs → añade al menos una FAQ específica de la entidad, o apóyate solo en las FAQs globales.

El widget muestra "Powered by Clione" pero estoy en Pro — Haz un hard refresh tras desactivar el branding; el widget cachea la política durante 5 minutos. Si persiste, revisa Org → Settings → Branding — el toggle puede no haberse guardado.

En BigCommerce Stencil, el widget carga pero el JSON-LD no incluye el contexto del producto — El global BCData de Stencil a veces no está listo cuando el widget se ejecuta. El widget reintenta hasta 3 veces con 500ms de delay, así que normalmente es transparente — pero si lo ves en un tema personalizado, asegúrate de que el script se carga async (no defer), DESPUÉS del bundle JS principal de la página.