Saltar al contenido principal

Snippet de tema Stencil — para crawlers sin JS

Audiencia: comerciantes de BigCommerce en un tema Stencil que se preocupan por una clase específica de crawler que NO evalúa JavaScript. Esto es adicional al Script Tag del Schema Injector, no un reemplazo.

Por qué existe​

El Schema Injector de Clione (ver SCHEMA_INJECTOR_BIGCOMMERCE.md) instala un <script> vía la Scripts API de BC. Ese script se ejecuta en el navegador e inyecta JSON-LD en <head> antes de que se dispare DOMContentLoaded. Los crawlers que ejecutan un navegador headless real — Google, Bing moderno, GPTBot, ClaudeBot, PerplexityBot, la flota de Common Crawl V2, todos los pipelines de entrenamiento de IA de Anthropic / OpenAI / Google — ven ese JSON-LD como si estuviera en el HTML original.

Pero un conjunto no trivial de crawlers no evalúa JavaScript en absoluto. Hacen fetch del HTML con algo equivalente a curl y parsean lo que reciben:

  • LinkedIn Post Inspector / debugger — usado por cualquiera compartiendo un enlace de producto en LinkedIn.
  • Facebook Sharing Debugger — misma idea, lado de Facebook. (FB renderiza JS ahora ocasionalmente, pero la UI del debugger no.)
  • Slack link unfurler — open-graph y un parser fino de JSON-LD, sin JS.
  • Herramientas de auditoría SEO antiguas — Screaming Frog (configuraciones antiguas), Sitebulb (configurable), algunas herramientas empresariales comerciales.
  • Scrapers de IA sin runtime V8 — cola larga de pipelines de datos internos, indexadores RAG, productos scraper-as-a-service que se envían sin navegador headless para ahorrar coste.

Para estos, el Script Tag es invisible — nunca lo ejecutan. La única manera de hacer visible el JSON-LD para ellos es ponerlo en el HTML que el servidor de BC devuelve. No hay manera solo-API de hacer esto en BC. Tienes que editar el tema Stencil.

Qué es y qué no es​

Este doc cubre el snippet mínimo de tema que descarga el JSON-LD de Clione server-side en tiempo de render del tema y lo inlinea en la respuesta HTML.

No es un reemplazo del Script Tag. El Script Tag gestiona el 95%+ del tráfico de crawlers y se actualiza dinámicamente sin deploy de tema. El snippet de tema es la opción de cinturón y tirantes para la cola larga, para tiendas que se preocupan por las previews de LinkedIn / Slack / FB y quieren las señales JSON-LD visibles para crawlers sin JS.

Requisitos previos​

  • La tienda está en un tema Stencil (no Catalyst / headless).
  • Tienes acceso de edición al tema activo vía el admin de BC (Storefront → Themes → Customize → Advanced → Edit theme files).
  • Tienes una API key activa de Clione con scope products:read.
  • El Script Tag del Schema Injector de Clione también está instalado — son complementarios, no alternativas.

El snippet​

Añade lo siguiente a templates/components/common/header.html (o el equivalente más cercano para tu tema), dentro de <head>, después de cualquier bloque meta-tag existente:

{{!-- Clione SEO — JSON-LD server-side para crawlers sin JS --}}
{{#if pages.contact}}{{/if}}{{!-- placeholder; quítalo si tu tema no tiene helpers de Handlebars --}}

<script type="application/ld+json" data-clione="theme-snippet">
{{!--
  Stencil no puede ir a buscar APIs externas en tiempo de render. El patrón
  de abajo usa el helper `inject` de BC para surface el id de entidad
  (product / category) y deja a un pequeño script inline de boot llamar a
  /api/v1/public/schema.jsonld en el first paint, luego escribir la
  respuesta en un hueco equivalente a noscript.

  Para crawlers VERDADERAMENTE sin JS (que por definición no ejecutarán
  esto), la única opción duradera es rellenar el snippet en tiempo de
  deploy usando la CLI `clione schema dump` (mira scripts/dump-schema.ts)
  y commit el fichero JSON resultante en los assets del tema, luego
  `{{ inject }}` el contenido en <head>. Documentado abajo en "Static
  fallback".
--}}
</script>

Variante dinámica (recomendada para la mayoría de tiendas)​

Para crawlers que SÍ evalúan JS pero quieres evitar el golpe síncrono de XMLHttpRequest del Script Tag, añade esto a templates/components/common/head.html:

{{#if product}}
  {{inject "clioneProductId" product.id}}
{{else if category}}
  {{inject "clioneCategoryId" category.id}}
{{/if}}

<script>
  (function () {
    var data = JSON.parse(document.getElementById('jsContext').innerHTML);
    var entityType = data.clioneProductId ? 'product'
                   : data.clioneCategoryId ? 'category'
                   : null;
    var entityId   = data.clioneProductId || data.clioneCategoryId;
    if (!entityType) return;

    var s = document.createElement('script');
    s.type = 'application/ld+json';
    s.setAttribute('data-clione', 'stencil-snippet');
    fetch('https://api.clione.ai/api/v1/public/schema.jsonld'
        + '?platform=bigcommerce&entityType=' + entityType
        + '&entityId=' + encodeURIComponent(entityId), {
      headers: { 'X-API-Key': 'PASTE_YOUR_API_KEY_HERE' },
    }).then(function (r) { return r.ok ? r.text() : null; })
      .then(function (t) { if (t) { s.text = t; document.head.appendChild(s); }});
  })();
</script>

Esto sigue requiriendo JS, así que es solo una respuesta parcial para crawlers sin JS. Usa el static fallback más abajo si realmente necesitas bytes-en-HTML.

Static fallback (para crawlers genuinamente sin JS)​

Este es el único enfoque que realmente pone bytes JSON-LD en el HTML que BC devuelve a un crawler equivalente a curl.

  1. Ejecuta npm run clione:dump-schema -- --store=YOUR_STORE_HASH --out=assets/clione-schema.json desde tu checkout local de las tools de Clione. Esto llama al mismo endpoint /schema.jsonld para cada producto / categoría publicada y escribe un bundle único.
  2. Commit assets/clione-schema.json en el tema Stencil activo vía el subidor de ficheros del Theme Editor (o stencil push si mantienes el tema fuera del admin).
  3. Añade a templates/components/common/header.html, dentro de <head>:
{{#if product}}
  <script type="application/ld+json" data-clione="static">
    {{{getAssetFromTheme "clione-schema.json" product.id}}}
  </script>
{{/if}}

Caveat: el bundle estático es un snapshot. No refleja cambios de Clione hasta que vuelves a ejecutar el dump y vuelves a hacer deploy. Para la mayoría de tiendas esto está bien si el bundle se refresca semanalmente vía un job de CI programado — Pulse te dirá cuándo se queda obsoleto (la métrica signal_stale_age).

Cuándo NO molestarse​

Si el tráfico de tu tienda es mayoritariamente Google / Bing orgánico + de pago + directo, y no publicas productos en LinkedIn o Slack como previews de enlace, sáltatelo entero. El Script Tag cubre todo lo que importa y la edición del tema es solo coste de mantenimiento.

Si SÍ publicas en LinkedIn / Slack / FB regularmente, y las previews de producto se ven flacas o mal ahí, haz la variante dinámica primero. Solo escala al static fallback si un crawler nombrado en concreto (con logs para probarlo) está perdiendo señales.

Relacionados​

  • SCHEMA_INJECTOR_BIGCOMMERCE.md — El lado del Script Tag. Instala ese primero.
  • PROPAGATION.md — Cómo las señales enriquecidas fluyen de Clione → metafields de BC → la fuente de datos del snippet.
  • PULSE_SCORING.md — Qué señales contribuyen al score de Pulse y cómo se detecta el staleness.