Saltar al contenido principal

Instala el Schema Injector

Planes: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓ (el Schema Injector está incluido en todos los planes)

El Schema Injector es la pequeña pieza de código que mete los structured data JSON-LD de Clione en el HTML de tu storefront para que motores de búsqueda y crawlers de IA puedan leerlos.

Sin él, el JSON-LD enriquecido vive en la BD de Clione pero nunca llega a tu tienda en vivo. Los crawlers ven la misma tienda de siempre.

El mecanismo es diferente en cada plataforma — e incluso en cada variante de cada plataforma. Esta página los recorre todos.

¿Qué camino te aplica?​

Tu setupQué instalarCómo
BigCommerce, tema Stencil (clásico / hosted storefront)Un script tag gestionado que Clione instala vía la Scripts API de BC.Un clic desde Settings, ver abajo.
BigCommerce, headless / Catalyst (Next.js, tipo Hydrogen)El SDK @clione/seo o una llamada directa a la SEO Signals API.Tarea de developer — consulta Integraciones headless.
Shopify, tema de Online Store (cualquier tema Liquid — Dawn, Sense, personalizado)El theme app block de Clione (sin script tag).Activar en el theme editor, ver abajo.
Shopify, Hydrogen / headlessEl SDK @clione/seo o la API directa.Tarea de developer — consulta Headless en Hydrogen.

Si no estás seguro de si estás en clásico o headless, casi seguro que no eres headless — headless requiere un repo de frontend custom-built que tu equipo de devs desplegó por separado.

BigCommerce — Stencil (storefront clásico)​

Paso 1 — Abre Settings de la tienda​

  1. Sidebar → elige la tienda BigCommerce.
  2. Settings (dentro de la tienda, no los ajustes globales de la cuenta).
  3. Desplázate hasta la tarjeta Schema Injector.

La tarjeta muestra uno de tres estados:

  • Not installed — botón verde de install + una nota "qué hace esto".
  • Installed — fecha de instalación, fecha de la última verificación, enlace para ver el script en vivo en tu storefront.
  • Error — normalmente un problema de credenciales o scope (ver Resolución de problemas).

Paso 2 — Instalar​

Pulsa Install Schema Injector.

Qué pasa entre bastidores:

  1. Clione crea una API key interna automáticamente (no necesitas gestionarla).
  2. Clione llama a la Scripts API de BigCommerce para registrar un script_tag de tipo src que carga desde https://api.clione.ai/embed/schema-injector/<your-store-id>.js.
  3. BigCommerce empieza a servir ese script en cada página del storefront.
  4. La tarjeta se refresca para mostrar el estado instalado.

El trabajo del script es obtener el JSON-LD enriquecido para la página actual (detectada vía OG tags + patrón de URL) e inyectarlo en el <head> como <script type="application/ld+json">. Los crawlers lo ven inmediatamente en la siguiente carga de página.

Paso 3 — Verificar​

  1. Abre cualquier página de producto enriquecido en una ventana de incógnito.
  2. Mira el código fuente (Ctrl/Cmd + U).
  3. Busca application/ld+json.
  4. Deberías ver el schema Product generado por Clione con el title, description y keywords enriquecidos, y (si los reviews están activos) aggregateRating.

También puedes pulsar Preview JSON-LD en la tarjeta del Schema Injector para ver lo que Clione inyectaría para una página específica sin salir del dashboard.

Paso 4 — Desinstalar​

Pulsa Uninstall en la tarjeta. Clione llama a la Scripts API de BigCommerce para borrar el script tag. La tarjeta vuelve a "Not installed". No se elimina ningún dato del lado de Clione — puedes reinstalar en cualquier momento.

Notas para BigCommerce​

  • embed.js existente detectado — Si Clione encuentra un script tag embed.js instalado manualmente en tu tienda (resto de una integración previa), el flujo de instalación lo detecta y pregunta si coexistir o reemplazar. El Schema Injector y el widget de FAQ renderizan tipos distintos de JSON-LD (Product vs FAQPage), así que pueden coexistir sin problema.
  • Marcador de comentario — El script inyectado va precedido de un comentario HTML (<!-- Clione Schema Injector -->) para que puedas detectarlo en el código fuente de la página y confirmar que se está renderizando.
  • Divisa — El priceCurrency del JSON-LD usa la divisa de la tienda desde el endpoint /v2/store de BigCommerce, NO un valor hardcoded. Verifica que la divisa de tu tienda es correcta en Settings → Store Profile en el admin de BC.

BigCommerce — headless / Catalyst​

No hay Schema Injector que instalar — tu frontend renderiza su propio <head>. Usa el SDK @clione/seo para obtener señales enriquecidas y renderizarlas tú:

import { getSignals } from '@clione/seo'

const signals = await getSignals('product', productId, {
  apiKey: process.env.CLIONE_API_KEY,
  storeId: process.env.CLIONE_STORE_ID,
})

// signals.jsonLd es un objeto Product schema listo para renderizar

Consulta Headless en Next.js para la integración completa. La tarjeta del Schema Injector en el dashboard dirá "Headless channel detected — install not applicable".

Shopify — Online Store (temas Liquid)​

Paso 1 — Asegúrate de que la custom app de Clione está instalada​

El theme app block viene incluido en la custom app de Clione que instalaste durante Conectar Shopify. Si saltaste la instalación de la app o la desinstalaste, no aparecerá ningún app block en tu theme editor.

Para confirmar: Shopify admin → Settings → Apps and sales channels → Develop apps → Clione AI → comprueba que App status es "Installed".

Paso 2 — Activa el bloque en tu tema en vivo​

  1. Shopify admin → Online Store → Themes.
  2. Encuentra tu tema en vivo → pulsa Customize.
  3. En el theme editor, pulsa el icono de pieza de puzzle (App embeds) en la columna izquierda.
  4. Desplázate para encontrar Clione JSON-LD.
  5. Activa el toggle.
  6. Pulsa Save (arriba a la derecha).

El bloque apunta a la región <head>, así que el JSON-LD se renderiza server-side por Liquid en cada página. No se necesita JavaScript y los crawlers lo ven en la primera petición.

Paso 3 — Verificar​

  1. Abre cualquier página de producto enriquecido en una ventana de incógnito.
  2. Mira el código fuente (Ctrl/Cmd + U).
  3. Busca application/ld+json.
  4. Deberías ver el schema Product generado por Clione.

Si un producto aún no se ha enriquecido, el metafield está vacío y el bloque Liquid no emite nada — sin script tag vacío roto. Es intencional.

Paso 4 — Activar el bloque en otros temas​

Si cambias de tema o trabajas en una preview de tema, necesitas activar el bloque otra vez — los app embeds de Shopify son por tema, no a nivel tienda.

Notas para Shopify​

  • meta_title y meta_description NO requieren el theme app block. Shopify los renderiza nativamente vía global.title_tag y global.description_tag en cada tema. Solo el JSON-LD necesita el bloque.
  • No se inyecta script tag. A diferencia de BigCommerce, el JSON-LD de Shopify se renderiza server-side por Liquid leyendo un metafield. No hay embed.js que instalar para JSON-LD.
  • El JSON-LD de Collection y Page están previstos pero aún no entregados. Hoy solo el schema Product se renderiza por el bloque. Las collections y pages aún obtienen meta title y description.

Shopify — Hydrogen / headless​

Igual que BigCommerce headless: no hay tema al que añadir el bloque. Usa el SDK @clione/seo o llama directamente a la SEO Signals API desde tu frontend.

Consulta Headless en Hydrogen.

Resolución de problemas​

BigCommerce​

"Install failed: 422 invalid field [html]" — Bug histórico, arreglado en la implementación actual del Schema Injector (usa kind=src en lugar de HTML inline). Si lo ves en una instalación fresca, abre un ticket de soporte — tu tenant puede estar pinned a una release antigua.

"Install failed: 403" — El scope Content en tu token de API de BigCommerce está en Read-only o None. El Schema Injector necesita Modify para registrar un managed script. Actualiza el scope en el token de API de BC y pulsa Install otra vez.

El JSON-LD no aparece en el código fuente tras instalar — Abre la página de producto directamente (no una preview de categoría) y fuerza un hard refresh (Ctrl/Cmd + Shift + R). El script necesita ejecutarse, así que funciona para crawlers que corren JS (Google, Bing, ChatGPT). Para crawlers sin JS, el propio script tag es visible en el código fuente pero el bloque JSON-LD inyectado por JS solo está ahí tras la ejecución — consulta Stencil crawlers sin JS para el camino alternativo de inyección server-side.

La tarjeta muestra "Installed" pero Verify falla — El script está registrado pero no se ejecuta. Causas habituales: el storefront está protegido por contraseña (usa un preview code — consulta el doc Verification), o la tienda usa un dominio personalizado que no resuelve. Abre el storefront en incógnito y confirma que carga.

Shopify​

"Clione JSON-LD" no es visible en App embeds — La custom app se instaló después del tema. Reinstala: Shopify admin → Develop apps → Clione AI → API credentials → Uninstall app → Install app. Recarga el theme editor y el bloque debería aparecer ahora.

Bloque activado pero no hay JSON-LD en el código fuente — El producto no está enriquecido. Abre el producto en el dashboard de Clione → comprueba el estado de Enrichment → enriquece si hace falta. El JSON-LD solo se renderiza para productos con el metafield clione.jsonld no vacío.

El JSON-LD aparece pero los datos parecen viejos — Los metafields de Shopify son eventualmente consistentes. Dale hasta 60 segundos tras el enriquecimiento para que el nuevo valor se refleje en el storefront. Si persiste, usa el botón Re-push to storefront en la pestaña Propagation del producto.

Cómo funciona la integración con la BC Scripts API​

El Schema Injector de BC es un único script global registrado vía la API Scripts Manager de BigCommerce. Por debajo:

  • Endpoint: POST /v3/content/scripts con payload { name, src, kind: "src", location: "head", visibility: "all_pages", consent_category: "essential" }.
  • La URL src es https://api.clione.ai/embed/schema-injector/<storeId>.js.
  • El trabajo del script es (a) detectar la entidad de la página leyendo og:type y el path, (b) llamar al endpoint público de embed de Clione para el JSON-LD de esa entidad, y (c) escribir un bloque <script type="application/ld+json"> dentro de <head>.
  • Un marcador de comentario HTML <!-- Clione Schema Injector --> se imprime antes del JSON-LD para que puedas verificar presencia incluso si el JSON-LD en sí está vacío (p. ej. para entidades no enriquecidas).

Por qué un script src y no HTML inline​

Versiones anteriores usaban HTML inline; la Scripts API de BC rechazaba el campo con un 422 en algunos casos. La implementación actual usa kind=src exclusivamente, que BC acepta sin restricciones.

Detección de un embed.js manual existente​

Si previamente instalaste el embed.js de Clione manualmente (camino de integración anterior), el flujo de instalación del Schema Injector lo detecta y te pregunta. El Schema Injector renderiza schema Product; el embed.js manual renderiza FAQ y posiblemente schema Product también. Elige:

  • Coexist — ambos corren. El Schema Injector deduplica los bloques Product para evitar doble emisión.
  • Replace — desinstala el embed.js manual e instala solo el Schema Injector.

Cómo funciona la Theme App Extension de Shopify​

La Theme App Extension va incluida en la custom app de Clione. Una vez activada por tema, inyecta tres cosas:

  1. Un tag <meta name="clione:version" content="...">.
  2. Un marcador de comentario HTML <!-- clione:jsonld -->.
  3. El bloque JSON-LD, leído desde el metafields.clione.jsonld por entidad.

Por tipo de página:

  • Product — Product schema, BreadcrumbList, FAQPage (si hay FAQs para el producto).
  • Collection — CollectionPage (previsto, no entregado).
  • Page — WebPage (previsto, no entregado).
  • Article — Article (previsto).

Por qué una Theme App Extension y no una sección Custom Liquid​

Una Theme App Extension es una integración gestionada por Shopify que se actualiza sin necesidad de que los merchants vuelvan a pegar código. Las secciones Custom Liquid requieren actualizaciones manuales cada vez que entregamos un cambio de schema. La Extension también sobrevive a actualizaciones de tema — las secciones Custom Liquid pueden ser borradas al reinstalar temas.

Comportamiento multi-tema​

La Extension se activa por tema, no a nivel tienda. Si previsualizas un tema diferente, necesitarás activar la Extension en ese tema también. El dashboard de Clione muestra una lista de temas con su estado de Extension bajo Store → Settings → Schema Injector → Themes.

Detección de headless / Catalyst (BigCommerce)​

Clione intenta detectar si tu tienda BC está usando un canal headless (Catalyst, BigCommerce Stencil headless, front-end custom) antes de mostrar el botón Install. Señales de detección:

  • La tienda tiene un channel_type de storefront con platform != 'bigcommerce'.
  • El setting Storefront URL apunta a un dominio que no es bigcommerce.com y no encaja con el patrón Stencil.

Si se detecta, la tarjeta del Schema Injector muestra un banner: "Headless channel detected — install the @clione/seo SDK instead. See Headless en Next.js."

Puedes hacer override de la detección (raro — solo si tienes ambos canales Stencil y headless) pulsando Install anyway en el banner.

Resumen de instalación por plataforma​

PlataformaQué se instalaDónde va¿Instalación de un clic?¿Removible?
BigCommerce StencilUn único script tag vía Scripts APITodas las páginas del storefront, headSíSí (botón Uninstall)
BigCommerce Catalyst / headlessNada — usa SDKN/AN/AN/A
Shopify Online StoreTheme App ExtensionTodas las páginas del storefront, headUn clic en el theme editorSí (toggle off en el theme editor)
Shopify Hydrogen / headlessNada — usa SDKN/AN/AN/A