Editor de FAQ + widget de embed

Planes: Growth · Pro · Agency (el editor de FAQ está plan-gated; el widget de embed está restringido por el editor — Starter no puede crear FAQs y por tanto no tiene nada que embeber)

Clione te permite crear FAQs por Product, Variant, Category (BigCommerce) / Collection (Shopify), Page o Globalmente — y luego servirlas en tu storefront con un único snippet de embed, con un bloque FAQPage JSON-LD acompañante para crawlers y LLMs.

Esta página trata sobre creación, generación, importación y el widget de embed. Para detalles de instalación por plataforma (BigCommerce Stencil, Catalyst headless, theme editor de Shopify, Hydrogen / Next), consulta Instalación del widget de FAQ.

Dónde vive

Sidebar → tienda → FAQs.

Cinco pestañas:

Browse — buscar, editar, soft-delete, restaurar.
Add — crear manualmente, una a una.
Generate — borradores LLM (Growth en adelante).
Import — subida bulk CSV.
Embed Script — obtén el snippet para tu storefront.

Paridad de entidades — a qué puedes adjuntar FAQs

Clione trata las FAQs como una entidad de primer nivel con la misma regla de paridad que el enriquecimiento: las FAQs funcionan en cada tipo de entidad en ambas plataformas.

Tipo de entidad	BigCommerce	Shopify	Notas
Product	yes	yes	El adjunto más común.
Variant	yes	yes	Útil para preguntas específicas de talla/color/material.
Category	yes	n/a	Categorías de BC.
Collection	n/a	yes	Collections de Shopify (mismo concepto).
Page	yes	yes	About / Shipping / FAQ content page.
Global	yes	yes	Aplica a cada render — envíos, devoluciones, garantía.

Las FAQs globales se fusionan con las FAQs específicas de entidad en cada render. Una página de producto muestra sus propias FAQs más el set global, en el orden que controlas con sortOrder.

1. Añadir FAQs manualmente

FAQs → Add:

Elige Entity Type (Product / Variant / Category / Collection / Page / Global).
Busca la entidad por nombre. El picker muestra display names, no IDs crudos.
- Para Global, no se selecciona ninguna entidad — la FAQ aplica a toda la tienda.
Escribe la Question y la Answer.
(Opcional) Pon el Locale si publicas varios idiomas.
(Opcional) Pon Sort Order para controlar el orden de display. Más bajo = primero.
Guarda.

Las FAQs nuevas son inmediatamente visibles para el widget de embed — sin paso de propagación.

2. Generar FAQs automáticamente (Growth en adelante)

FAQs → Generate está plan-gated. En Starter la pestaña está oculta — toda la sección FAQ está detrás de una ruta LockedFeature feature="faq". Growth, Pro y Agency la ven.

El panel Generate envía los datos enriquecidos de la entidad (title, identity, reasoning, keywords) a tu LLM y recibe un pequeño batch de pares Q&A sugeridos. Puedes:

Elegir el alcance — una entidad, una lista de entidades o "todo en esta tienda".
Elegir cuántos borradores por entidad (por defecto 5, máx 10).
Pulsar Generate.

Los borradores se guardan automáticamente como status=approved y listos para servir. Edita o borra los que no te gusten desde la pestaña Browse.

El coste LLM se cuenta contra la cuota de enrichment de tu plan — generar 50 FAQs de producto cuenta como 50 llamadas de enrichment.

3. Importar en bulk (CSV)

FAQs → Import acepta un CSV con esta cabecera:

entityType,entityId,question,answer,locale,sortOrder
product,SKU-001,What is the warranty?,2-year manufacturer warranty,en,0
collection,summer-sale,When does the sale end?,Sunday at midnight CET,en,0
global,,What are your shipping times?,2–5 business days within the EU,en,0

Notas:

entityType acepta: product, variant, category, collection, page, global.
entityId está vacío para global. Para todo lo demás, usa el ID nativo de la plataforma (BC product ID, Shopify GID, page handle, etc.).
locale es una etiqueta BCP-47 (en, es, es-ES, fr-FR). El widget filtra por el atributo lang de la página cuando está presente.
sortOrder es entero, ascendente. Por defecto 0.
La fila de cabecera es requerida. Encoding UTF-8. Usuarios de Excel: guarda como "CSV UTF-8".

El importador deduplica por (entityType, entityId, question, locale). Re-importar una fila actualiza answer y sortOrder; el ID de FAQ se preserva para que la caché del embed no se invalide.

4. Exportar

Dos caminos:

Por entidad — en Browse, filtra por entidad y pulsa ↓ Export CSV.
Toda la tienda — arriba de la página FAQs → ↓ Download all FAQs (CSV). Un archivo, cada FAQ de cada entidad, globals incluidas.

El export usa el mismo set de columnas que Import, así que un round-trip (export → editar en Excel → re-importar) es no destructivo.

FAQs → Embed Script es la fuente del snippet que pegas en tu storefront.

Setup requerido

Antes de que el widget pueda obtener nada, necesitas:

Una API key con el scope products:read.
Al menos un Allowed Domain en esa key (p. ej. shop.example.com, *.example.com).

Ambos se configuran en Store → Settings → API Keys — consulta Ajustes de la tienda y Autenticación API. Sin allowedDomains, el widget recibe 403 desde la API para bloquear scraping.

El snippet

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

El loader auto-detecta la entidad de la página actual desde, en orden:

Atributos data-entity-type + data-entity-id en el script tag (override explícito).
Meta tags OpenGraph (og:type="product", product:retailer_item_id).
Patrones de URL: Shopify /products/, /collections/; BigCommerce /product/, URLs de categoría; clases body de WooCommerce; etc.

Luego obtiene las FAQs matching (específicas de entidad + global, fusionadas), e inyecta:

Un acordeón visible en el selector destino.
Un bloque invisible JSON-LD FAQPage para crawlers e ingesta LLM.

Badge "Powered by Clione"

Los planes Starter y Trial renderizan un pequeño badge Powered by Clione al final del acordeón. El badge se queda — quitarlo requiere Growth o superior y se controla desde Org → Brand, consulta Ajustes de branding.

Esto es política, no bug. El toggle de branding en Settings está deshabilitado en Starter / Trial y la API lo refuerza también del lado del embed.

Instalación por plataforma

El snippet en sí es el mismo en cada storefront, pero dónde lo pegas difiere:

BigCommerce Stencil — footer global o inyección por template.
BigCommerce headless / Catalyst — import en componente de página.
Theme editor de Shopify — bloque Custom Liquid o theme.liquid.
Hydrogen / Next.js / Nuxt — consulta las guías headless en el sidebar Developers.

El paso a paso completo vive en Instalación del widget de FAQ. El Schema Injector de BigCommerce (que auto-instala el plumbing JSON-LD para productos) es una funcionalidad separada — consulta Schema injector.

Resolución de problemas

El widget renderiza vacío — la lista de FAQ devolvió 0. Comprueba: (1) tienes FAQs para esta entidad o globalmente, (2) el filtro de locale coincide con el <html lang> de la página, (3) no estás sobre un ID de entidad en draft / sin publicar.

403 Forbidden — el Origin / Referer de la petición no está en allowedDomains para la API key. Añade el dominio en la key y recarga.

El JSON-LD no aparece en View Source — en Shopify, el JSON-LD requiere que el theme app block esté activado. En BC, el snippet de embed lo escribe directamente. Consulta Schema injector para los detalles específicos de plataforma.

La pestaña Generate no aparece — tu plan no incluye feature=faq. Sube a Growth o superior en Billing.

El widget renderiza FAQs pero falta el JSON-LD — Comprueba que el script tag del widget de FAQ se carga antes que cualquier otro script que emita JSON-LD. El widget hace append al head; si otro script borra el head después, el JSON-LD desaparece. Inspecciona con las dev tools del navegador (Elements → head → busca FAQPage).

Las FAQs se duplican entre varios renders de página — Habitual cuando el script del widget se carga dos veces (p. ej. una vez en la cabecera del tema y otra en un template personalizado). Confirma que solo existe un script tag con src="api.clione.ai/embed.js" por página.

El filtro de locale muestra todas las FAQs sin importar el <html lang> — El atributo lang de la página puede estar ausente o mal formado (se espera BCP-47). Inspecciona con document.documentElement.lang en la consola. Añade el atributo del lado del servidor (BC: edita el elemento <html> del tema; Shopify: asegúrate de que el idioma de tus Markets está configurado).

Notas por plataforma para crear FAQs

BigCommerce

FAQs de Variant — las variantes de producto BC son entidades de primer nivel con sus propios IDs. Cuando adjuntas una FAQ a una variante en el editor, el entity picker muestra la selección de option de la variante (p. ej. "Size: M, Color: Blue"). La FAQ renderiza solo en el estado seleccionado de la variante, que los templates de tema de BC exponen vía el query string variant_id.
FAQs de Category — renderizan arriba de la descripción de la categoría en el template BC Stencil.
FAQs de Page — renderizan al final de las content pages de BC.
FAQs Global — renderizan en cada página donde se ejecute el script del widget.

Shopify

FAQs de Variant — las variantes de Shopify tienen un variantId por combinación de option. El widget detecta la variante actual desde el selector de variantes de la página y muestra las FAQs específicas de variante. Nota: los temas que no disparan un re-render al cambiar de variante no refrescarán la lista de FAQ — el widget polea el parámetro de URL ?variant= y vuelve a fetch al cambiar.
FAQs de Collection — renderizan arriba de la página de collection por encima del grid de productos.
FAQs de Page — renderizan al final de las content pages de Shopify.
FAQs Global — renderizan en cada página donde se ejecute el script del widget.

Detalles del coste de generación

La pestaña Generate cuenta cada FAQ generada contra la cuota de créditos de enrichment:

1 producto × 5 FAQs = 5 créditos.
1 producto × 10 FAQs (máx) = 10 créditos.
50 productos × 5 FAQs = 250 créditos.

El dashboard muestra el consumo de créditos proyectado antes de que pulses Generate. Puedes cancelar antes de la confirmación de coste si excede tu presupuesto.

Script de embed — referencia completa

El script de embed (https://api.clione.ai/embed.js) acepta los siguientes atributos data-*:

Atributo	Requerido	Por defecto	Descripción
`data-api-key`	Sí	—	API key de tu tienda con scope `products:read`.
`data-target`	No	`#clione-faq`	Selector CSS donde se monta el widget.
`data-entity-type`	No	auto-detect	Override: `product`, `variant`, `category`, `collection`, `page`.
`data-entity-id`	No	auto-detect	Override del entity ID.
`data-locale`	No	lang de la página	Forzar un locale específico.
`data-max`	No	10	Número máximo de FAQs a mostrar.
`data-theme`	No	`auto`	`light`, `dark` o `auto` (sigue la preferencia del SO).
`data-render-json-ld`	No	`true`	Poner a `false` para suprimir el bloque JSON-LD (si renderizas el tuyo).
`data-debug`	No	`false`	Loguea las decisiones de detección + fetch en la consola.

Dónde vive​

Paridad de entidades — a qué puedes adjuntar FAQs​

1. Añadir FAQs manualmente​

2. Generar FAQs automáticamente (Growth en adelante)​

3. Importar en bulk (CSV)​

4. Exportar​

5. El widget de embed​

Setup requerido​

El snippet​

Badge "Powered by Clione"​

Instalación por plataforma​

Resolución de problemas​

Notas por plataforma para crear FAQs​

BigCommerce​

Shopify​

Detalles del coste de generación​

Script de embed — referencia completa​