Saltar al contenido principal

Instala el widget de FAQ en tu storefront

El widget de FAQ es el acordeón visible con las FAQs en las páginas de tu storefront, para que tus clientes las lean. Esas mismas FAQs llegan a los crawlers y a los asistentes de IA como datos estructurados FAQPage dentro del @graph de JSON-LD de la página, que llega cuando publicas la entidad.

Cómo llega el acordeón a la página depende de tu plataforma:

Tu storefrontQué pinta el acordeón
BigCommerce StencilEl script del Schema Injector
BigCommerce headless / CatalystTu frontend, con la API de FAQs
Shopify Online StoreEl app embed Clione FAQ de la app de Shopify de Clione
Shopify Hydrogen / headlessTu frontend, con la API de FAQs
WordPress o cualquier otra webEl script de embed, embed.js

Para escribir FAQs, mira el editor de FAQs. Esta página trata solo de llevarlas al storefront. Solo se muestran las FAQs aprobadas.

El editor de FAQs está incluido en Growth, Pro y Agency. Enseñar FAQs en tu storefront nunca gasta créditos.

BigCommerce — Stencil (storefront clásico)​

El acordeón lo pinta el script del Schema Injector. Instálalo una vez desde Ajustes de la tienda → Inyector de Schema → Instalar: mira Schema Injector. No hay que pegar nada más.

No añadas además el snippet de embed.js: dos scripts de Clione en la misma página pintan las FAQs dos veces. La instalación del Schema Injector te avisa si encuentra uno puesto a mano.

Elige dónde aparece​

El acordeón se coloca con lo primero de esta lista que se cumpla:

  1. Un ancla en tu tema. Añade un elemento vacío con el atributo data-clione-faq donde quieras el acordeón; por ejemplo, justo después de la descripción del producto en los ficheros de tu tema:

    <div data-clione-faq></div>

  2. El ajuste de ubicación. Preguntas frecuentes → Avanzado → Estilo → Ubicación del widget de FAQ: inserta el acordeón Antes del elemento o Después del elemento que coincida con un selector CSS, para todas las páginas (Por defecto) o por tipo de entidad (Productos, Categorías, Colecciones, Contenido).

  3. Si no, al final del contenido principal de la página.

En BigCommerce, los atributos data-style-* de abajo van en ese elemento data-clione-faq, porque el script en sí pertenece al Script Manager.

Comprobar​

  1. Abre en una ventana de incógnito una página de producto con FAQs aprobadas.
  2. El acordeón aparece donde lo colocaste cuando la página termina de cargar.
  3. Mira el código fuente (Ctrl/Cmd + U) y busca FAQPage: está dentro del bloque @graph marcado con data-clione="schema-graph", una vez publicado el producto.

BigCommerce — headless / Catalyst​

Renderiza las FAQs en el servidor desde tu frontend con la API de FAQs:

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 { data } = await res.json()
// data es null cuando la entidad no tiene FAQs. Si no:
//   data.entries    → [{ question, answer }, …]
//   data.htmlBlock  → el HTML del acordeón, listo para pintar
//   data.jsonLd     → el objeto FAQPage
//   data.scriptTag  → el mismo FAQPage dentro de <script type="application/ld+json">
//   data.entryCount → número de FAQs

Parámetros opcionales: locale y pageUrl. Tienes la referencia completa en API de FAQs, y más en Headless con Next.js.

Shopify — Online Store (temas Liquid)​

En Shopify, el acordeón viene con la app de Shopify de Clione, la que instalas al conectar Shopify. Activa su app embed Clione FAQ:

  1. Admin de Shopify → Tienda online → Temas → en tu tema publicado, haz clic en Personalizar.
  2. Abre Incrustaciones de aplicaciones (App embeds) en la barra de la izquierda.
  3. Activa Clione FAQ (y Clione SEO, que lleva los datos estructurados).
  4. Haz clic en Guardar.

Shopify renderiza el HTML del acordeón en el servidor como parte de la página, así que está en el HTML incluso para los crawlers que no ejecutan JavaScript. Al cargar la página, se mueve a un elemento con el atributo data-clione-faq si tu tema lo tiene (añade <div data-clione-faq></div> donde lo quieras) o, si no, justo encima del pie de página.

Los app embeds van por tema: si cambias de tema, vuelve a activarlo en el nuevo.

Comprobar​

  1. Abre en una ventana de incógnito una página de producto publicada con FAQs aprobadas.
  2. El acordeón aparece donde lo colocaste.
  3. Ajustes de la tienda → Inyector de Schema → Estado del Schema revisa tu storefront real y te dice si el acordeón de FAQ está en la página comprobada.

Shopify — Hydrogen / headless​

Igual que en BigCommerce headless: llama a la API de FAQs desde el loader de tu ruta y pinta en tu componente el HTML del acordeón y los datos estructurados. Mira Headless con Hydrogen.

WordPress y otros storefronts: el script de embed​

Para cualquier otra web, usa el snippet que te prepara Preguntas frecuentes → Script de inserción (plataforma, clave de API restringida a tu dominio y estilos). Tiene esta pinta:

<div id="clione-faq"></div>
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-platform="generic"
  async
></script>

El script detecta de qué entidad trata la página y pinta sus FAQs. Si en un tema a medida no la detecta, indícala tú:

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

Sin data-target, el acordeón va dentro de un elemento con data-clione-faq o justo antes del pie de página. Tienes la lista completa de atributos en el editor de FAQs.

El script de embed funciona en el navegador, así que los crawlers que no ejecutan JavaScript no ven lo que añade. Si eso le importa a tu web, renderiza en el servidor con la API de FAQs.

Dominios permitidos​

La clave de API solo responde a peticiones de los dominios de su lista; cualquier otro recibe un 403 y no se pinta nada. La pestaña Script de inserción restringe la clave al dominio de tu storefront por ti. Para cambiar la lista, ve a Ajustes de la tienda → Claves API. Los comodines funcionan (*.ejemplo.com), así que también puedes cubrir un subdominio de staging.

Personaliza el aspecto: atributos data-style-*​

El acordeón lee ajustes de estilo de los atributos data-style-*, así que puedes adaptarlo a tu marca sin tocar CSS. Ponlos en la etiqueta del script de embed o, en BigCommerce Stencil, en tu elemento data-clione-faq. Todos son opcionales; si quitas uno, se usa el valor por defecto.

AtributoPor defecto (BigCommerce Stencil)Por defecto (script de embed)Qué controla
data-style-accentcurrentColorcurrentColorColor de acento: la flecha de abrir/cerrar y la línea bajo el título.
data-style-fginheritinherit (preguntas #1a1a2e, respuestas #374151)Color del texto del título, las preguntas y las respuestas.
data-style-bgtransparenttransparentFondo de todo el bloque de FAQs.
data-style-borderrgba(0,0,0,0.1)#e5e7ebColor del contorno y de las líneas entre preguntas.
data-style-border-width1px1pxGrosor de la línea entre preguntas.
data-style-radius8px0Radio de las esquinas del bloque.
data-style-fontinheritinheritTipografía. Por defecto, la de tu tema.
data-style-font-sizeinherit1rem (preguntas), 0.95rem (respuestas)Tamaño de letra base de preguntas y respuestas.
data-style-spacing1em12pxRelleno dentro de cada fila de pregunta.
data-style-line-height1.61.5 (preguntas), 1.6 (respuestas)Interlineado de las respuestas.
data-style-heading-weight600700Grosor de letra del título.
data-style-heading-border-width02pxGrosor de la línea bajo el título; 0 la oculta.
data-style-question-weight600600Grosor de letra de las preguntas.
data-style-answer-weight400400Grosor de letra de las respuestas.
data-style-max-widthninguno800pxAncho máximo; si lo pones, el bloque se centra solo. Con el script de embed, un número sin unidad se lee como píxeles; en BigCommerce escribe la unidad (720px).
data-style-theme——En BigCommerce Stencil, dark viene incluido y cualquier otro valor añade una clase clione-faq-theme-<nombre> para tu propio CSS. Con el script de embed, cualquier valor solo añade esa clase.

En el elemento data-clione-faq de BigCommerce también puedes poner data-style="minimal" (solo estructura, sin caja ni color) o data-style="default" (tarjeta con caja), data-heading para cambiar el texto del título y data-locale para elegir la traducción incluida del título.

El paso Dar estilo al widget de Preguntas frecuentes → Script de inserción tiene un formulario en vivo para colores, tipografía, espaciado, tema y ancho máximo, y escribe estos atributos en el snippet por ti. En BigCommerce, el CSS personalizado que guardes en Preguntas frecuentes → Avanzado → Estilo lo aplica el Schema Injector al acordeón. Más ejemplos: Personalización del widget de FAQ.

Insignia "Powered by Clione"​

El acordeón que pintan el script de embed y la FAQ API muestra una pequeña insignia Powered by Clione. Viene activada; la desactivas con Mostrar «Powered by Clione» en el widget de FAQ, en Ajustes de la tienda → General → Marca. Durante la prueba siempre aparece. El acordeón del Schema Injector de BigCommerce y el app embed Clione FAQ de Shopify no la muestran.

Problemas frecuentes​

403 Forbidden en la consola del navegador (script de embed): el dominio de la página no está entre los dominios permitidos de la clave de API. Cambia la lista en Ajustes de la tienda → Claves API.

El acordeón está vacío o no aparece en algunas páginas: esas entidades no tienen FAQs aprobadas. Abre la entidad en Clione → pestaña Preguntas frecuentes y añade o aprueba alguna, o enlaza una respuesta de la biblioteca.

Las FAQs salen dos veces: hay dos piezas de Clione pintando en la misma página: el script de embed además del Schema Injector (BigCommerce) o del app embed Clione FAQ (Shopify), o el script de embed cargado dos veces. Deja solo una.

BigCommerce: el acordeón sale en mal sitio: añade un elemento data-clione-faq donde lo quieras, o configura la Ubicación del widget de FAQ. Un ancla en la página siempre gana al ajuste de ubicación.

Shopify: no aparece el acordeón: comprueba que Clione FAQ está activado y guardado en tu tema publicado y que la app de Shopify de Clione está instalada. Después pasa el Estado del Schema a esa página.