Cómo llevar un dato de BigCommerce, por el tema, un widget o un script, a la ficha publicada y a su JSON-LD

Has rellenado los custom fields de un producto, has arrastrado un widget en Page Builder o has pegado un script en Script Manager, y quieres saber si eso está en tu ficha de producto publicada. En BigCommerce no basta con mirar el panel: entre el panel y la página hay un tema que decide qué se pinta, una placement que puede estar inactiva y un botón de publicar. Esta guía sigue cada camino hasta el código fuente de la ficha, con lo que dice la documentación de BigCommerce de cada paso, y acaba en algo que puedes ver: el HTML.

Por dónde pasa un dato, y dónde se pierde

En una tienda con tema Stencil, la ficha la compone el tema. Sus plantillas usan Handlebars, y en producción esas instrucciones se ejecutan en el servidor y generan el HTML que recibe el navegador.⁠^{[1]BigCommerce Dev Center. Stencil Technology Stack} Es renderizado del lado del servidor: lo que el tema pinta está en el código fuente antes de que se ejecute ningún JavaScript. Hasta ese HTML se llega por tres caminos, y Catalyst, el frontend headless de BigCommerce, cambia las reglas de los tres:

Los cinco pasos siguientes recorren la tabla en orden: el dato, la plantilla, el widget, el script y la página publicada.

Paso 1: comprueba que el dato está en el producto

Antes de buscar un dato en la página, confirma que existe donde el tema va a buscarlo. Para una ficha, eso es el producto:

• Los campos SEO. El título SEO y la meta description de cada producto se editan en el propio producto, en su sección SEO.⁠^{[8]BigCommerce, centro de ayuda. SEO Fields} Si están vacíos, lo que pinte el tema en su lugar es cosa del tema.
• Los custom fields. Son pares de nombre y valor; los dos campos son obligatorios, cada par tiene que ser único dentro del producto y hay un máximo de 200 por producto y 250 caracteres por campo.⁠^{[9]BigCommerce API Reference. Create Product Custom Field}
• Los identificadores. SKU, MPN y GTIN. En Cornerstone, el bloque de datos estructurados escribe cada uno solo si el producto lo tiene, como verás en el paso 2.⁠^{[10]BigCommerce en GitHub. Cornerstone, el tema Stencil por defecto (release 6.22.0): templates/pages/product.html, templates/components/products/ y templates/layout/base.html}

Si el dato no está en el producto, ningún tema lo va a pintar. Si está, el siguiente sospechoso es la plantilla.

Paso 2: lee qué pinta la plantilla de tu tema

Una plantilla de Stencil solo puede pintar los datos que tiene a mano. La de la ficha, product.html, recibe el objeto del producto por defecto; los datos extra (reseñas, productos relacionados, vídeos) se piden con un bloque de front matter en YAML al principio de los archivos de templates/pages, y no se pueden pedir desde templates/components ni desde templates/layout.⁠^{[11]BigCommerce Dev Center. Using Front Matter}

En Cornerstone 6.22.0, el tema por defecto, la ficha se monta así:⁠^{[10]BigCommerce en GitHub. Cornerstone, el tema Stencil por defecto (release 6.22.0): templates/pages/product.html, templates/components/products/ y templates/layout/base.html}

• templates/pages/product.html llama a la vista del producto, declara la región product_below_content y, al final, incluye components/products/schema, que es el bloque JSON-LD.
• La vista del producto pinta el nombre en el <h1>, declara la región product_below_price y pinta los custom fields en la lista de detalles, salvo que el ajuste del tema show_custom_fields_tabs esté activo, que los lleva a una pestaña.
• La plantilla de los custom fields recorre la lista del producto y escribe cada par como un término y su definición:

{{#each product.custom_fields}}
  <dt class="productView-info-name">{{name}}:</dt>
  <dd class="productView-info-value">{{{value}}}</dd>
{{/each}}

El bloque de datos estructurados es un Product con el nombre, el SKU, el MPN y el GTIN si existen, la URL, la marca, la descripción recortada a 4.000 caracteres, la imagen principal, las valoraciones y las reseñas si la tienda las muestra, y una oferta con la moneda, el precio (o el mínimo y el máximo si hay un rango), el estado, la disponibilidad y una fecha de validez del precio que la plantilla calcula como un año después del día en que se genera la página.⁠^{[10]BigCommerce en GitHub. Cornerstone, el tema Stencil por defecto (release 6.22.0): templates/pages/product.html, templates/components/products/ y templates/layout/base.html} Y dos ausencias: el nodo no lleva @id y no incluye ningún custom field. El tejido de una camisa sale en la ficha para quien la lee, y no sale en su marcado.

Eso es Cornerstone. Un tema del marketplace o de una agencia también es Stencil, pero trae sus propias plantillas, así que lo que hace el tuyo solo lo sabes leyendo sus archivos o el HTML que genera. Si vas a tocarlos, BigCommerce lo dice en sus propios ejercicios: haz antes una copia del tema y prueba los cambios en la copia.⁠^{[12]BigCommerce Developer Learning. Mini Use Case: Create a Customized Field}

Paso 3: sigue el widget hasta su región

Un widget de BigCommerce llega a la ficha por una de dos puertas, y las dos acaban en el mismo sitio.

Page Builder, para quien no programa. Se abre en Storefront › Themes › Edit in Page Builder, solo en tiendas con tema Stencil. Los widgets se arrastran desde el menú de la izquierda a una de las regiones que trae el tema, y hay uno de HTML que admite cualquier HTML. La regla que más se olvida: guardar no publica. Según el centro de ayuda, los cambios guardados no se ven en la tienda hasta que pulsas «Publish».⁠^{[4]BigCommerce, centro de ayuda. Page Builder} Por debajo, Page Builder mete los widgets con la Widgets API, el mismo mecanismo que usan los widgets de la propia plataforma.⁠^{[13]BigCommerce Dev Center. Page Builder Overview}

La Widgets API, para una aplicación o una agencia. Un widget es una plantilla con Handlebars más una configuración, un JSON de hasta 64 KB que lleva el contenido que la plantilla pinta. Para que aparezca en la tienda hace falta una placement, que decide en qué región va y en qué orden.⁠^{[2]BigCommerce Dev Center. Widgets API} Al crearla, cuatro campos deciden si la ves:⁠^{[3]BigCommerce API Reference. Create Placement}

• template_file: la plantilla de página, pages/product para las fichas.
• entity_id: el ID del producto, si el widget es solo para esa ficha. Sin él, sale en todas.
• channel_id: el canal; si no lo indicas, el primero que se creó en la tienda.
• status: active o inactive, y por defecto es inactive.

La región tiene que existir en el tema activo. El endpoint GET /v3/content/regions?template_file=pages/product devuelve las regiones que el tema declara en esa plantilla,⁠^{[14]BigCommerce API Reference. List Theme Regions} y en Cornerstone 6.22.0 la ficha tiene dos, product_below_price y product_below_content.⁠^{[10]BigCommerce en GitHub. Cornerstone, el tema Stencil por defecto (release 6.22.0): templates/pages/product.html, templates/components/products/ y templates/layout/base.html} El límite que llega pronto en un catálogo grande: 75 placements por plantilla de página.⁠^{[2]BigCommerce Dev Center. Widgets API}

Lo que publica un widget está en su configuración, no en el catálogo: BigCommerce define la configuración como el JSON con el contenido que la plantilla puede pintar.⁠^{[2]BigCommerce Dev Center. Widgets API} Si un widget lleva el marcado de una ficha, el precio que muestra es el que se escribió en su configuración, y cuando cambia el del producto alguien tiene que actualizar el widget. Y una más para quien instala aplicaciones: el contenido que crea el widget de una aplicación se queda en la tienda aunque la desinstales.⁠^{[15]BigCommerce Dev Center. Third-Party Widgets}

En el HTML, la región y el widget se reconocen por dos atributos; la placement no deja ninguna marca.⁠^{[2]BigCommerce Dev Center. Widgets API} Esto es lo que buscas en la ficha (ejemplo ficticio, simplificado):

<div data-content-region="product_below_content">
  <div data-widget-id="00000000-0000-4000-8000-000000000001">
    <script type="application/ld+json">
      { "@context": "https://schema.org", "@type": "Product", ... }
    </script>
  </div>
</div>

Que el marcado quede en el <body> no es un problema para Google: el JSON-LD va en una etiqueta <script> dentro del <head> o del <body>, y Google también lo lee cuando lo inyectan los widgets de un gestor de contenidos. Lo usa para entender la página y para mostrar resultados enriquecidos.⁠^{[16]Google Search Central. Introduction to structured data markup in Google Search}

Paso 4: revisa Script Manager y los huecos del tema

Script Manager está en Storefront › Script Manager y, según el centro de ayuda, es una función de las tiendas con tema Stencil.⁠^{[6]BigCommerce, centro de ayuda. Using Script Manager} (Catalyst lee sus scripts a su manera, como verás al final.) Cada script se configura con:⁠^{[6]BigCommerce, centro de ayuda. Using Script Manager}

• la colocación, en la cabecera o en el pie;
• las páginas donde se carga: las de la tienda, el checkout, la confirmación del pedido o todas;
• la categoría para el banner de cookies: esenciales, analítica, funcionales o publicidad;
• el tipo: una URL o el código pegado, hasta 64 KB.

Fíjate en la segunda línea: Script Manager trabaja por tipo de página, no por producto. Un script para fichas sale en todas las fichas, así que no sirve para el marcado de un producto concreto. Para eso está el entity_id de un widget.

El script llega a la página por dos huecos del tema. En Stencil, va al objeto de la cabecera o al del pie, y si la plantilla no tiene esas expresiones, los scripts de esa ubicación no se pintan.⁠^{[5]BigCommerce Dev Center. Scripts API} Cornerstone 6.22.0 las tiene en templates/layout/base.html, la primera antes del cierre del <head> y la segunda al final del <body>:⁠^{[10]BigCommerce en GitHub. Cornerstone, el tema Stencil por defecto (release 6.22.0): templates/pages/product.html, templates/components/products/ y templates/layout/base.html}

    {{{head.scripts}}}
  </head>
  ...
    {{{footer.scripts}}}
  </body>

Un tema modificado que haya perdido una de las dos deja sin pintar, en silencio, todo lo que Script Manager mande a esa ubicación. Tres avisos más de BigCommerce:

• Los cambios tardan unos segundos. Los scripts tienen una caché de 20 segundos, así que uno recién creado, cambiado o borrado puede no verse en la tienda al momento.⁠^{[6]BigCommerce, centro de ayuda. Using Script Manager}
• En local no se ven. Si desarrollas el tema con Stencil CLI, los scripts creados con la Scripts API no se pintan.⁠^{[5]BigCommerce Dev Center. Scripts API}
• El banner de cookies decide. Con el banner activo, el comprador puede rechazar categorías de scripts; de los esenciales no se puede salir.⁠^{[6]BigCommerce, centro de ayuda. Using Script Manager} Cuando compruebes la ficha, hazlo también sin aceptar nada.

Si lo que metes por Script Manager es datos estructurados, distingue dos casos. Un bloque application/ld+json pegado tal cual es texto que el tema escribe en el HTML como cualquier otro script. Un script que construye el marcado con JavaScript después de cargar es otra cosa: Google avisa de que el marcado de producto generado así puede hacer los rastreos de Shopping menos frecuentes y menos fiables, un problema para datos que cambian rápido, como el precio y la disponibilidad.⁠^{[17]Google Search Central. Generate structured data with JavaScript}

Paso 5: compruébalo en el HTML publicado

Abre la ficha y pide su código fuente: «Ver código fuente de la página» en el menú del botón derecho, o view-source: delante de la URL. No uses el inspector de las herramientas para desarrolladores, que enseña la página después de ejecutar JavaScript. Busca:

• El valor exacto del dato: el texto de un custom field, el título de la página, la meta description.
• data-content-region, para ver las regiones que declara tu tema, y data-widget-id, para ver los widgets que han caído en ellas.⁠^{[2]BigCommerce Dev Center. Widgets API}
• application/ld+json: cuántos bloques hay y qué @type declara cada uno. En una ficha con el bloque del tema y el de un widget habrá dos Product, y conviene saber de dónde sale cada uno.
• Los scripts de Script Manager, en la cabecera o justo antes del cierre del <body>, según la colocación que elegiste.

Lo que encuentras en el código fuente llega en cualquier descarga. Lo que ves en la página y no está ahí lo ha puesto JavaScript, y solo lo lee un rastreador que renderiza; la guía sobre qué ve un rastreador de IA explica quién lo hace y quién no.

Después, mira lo que ve Google:

• La Prueba de resultados enriquecidos con la URL, no pegando el código, porque con el código hay límites de JavaScript.⁠^{[17]Google Search Central. Generate structured data with JavaScript} Entra como móvil salvo que elijas otra cosa y dice qué tipos de resultados enriquecidos encuentra, con sus errores y sugerencias.⁠^{[18]Ayuda de Search Console. Rich Results Test}
• La inspección de URLs de Search Console. «Ver página rastreada» enseña el HTML que devolvió tu servidor, las cabeceras, la consola de JavaScript y los recursos cargados, y la prueba en directo examina la URL en ese momento, así que puede no coincidir con la versión indexada.⁠^{[19]Ayuda de Search Console. URL Inspection tool}

Si lo que quieres es revisar el marcado en sí, está la guía para auditar los datos estructurados de una ficha. Y conviene no confundir los dos verbos: validar el marcado no es lo mismo que verificar que se publica. Lo segundo, comprobar en la página viva que cada señal está, es la verificación de publicación.

Si tu tienda está en Catalyst

Catalyst es el frontend headless de BigCommerce: una aplicación de Next.js con componentes de servidor de React que pide los datos a la API de escaparate en GraphQL y que se aloja en Vercel, en otro proveedor que admita Next.js o, en beta cerrada, en la propia BigCommerce.⁠^{[7]BigCommerce Dev Center. Catalyst} No carga las plantillas de Stencil, y eso cambia los tres caminos:

• Widgets. Sin plantillas de Stencil no hay regiones, que es donde caen los widgets.⁠^{[2]BigCommerce Dev Center. Widgets API} El equivalente a Page Builder es Makeswift, el editor visual integrado en una versión de Catalyst, y las aplicaciones que modifican el escaparate, según la propia BigCommerce, en general no funcionan con Catalyst.⁠^{[20]BigCommerce Dev Center. Features (Catalyst)}
• Scripts. Catalyst lee los scripts de Script Manager configurados para todas las páginas o para las de la tienda, ignora el resto y los carga en el navegador con una biblioteca de consentimiento; si la tienda tiene el banner activo, los no esenciales esperan a que el comprador acepte su categoría.⁠^{[21]BigCommerce Dev Center. Install Scripts in Catalyst} Los scripts con expresiones Handlebars hechos para Stencil no funcionan en Catalyst,⁠^{[20]BigCommerce Dev Center. Features (Catalyst)} y las versiones anteriores a la 1.1 no pintan los de la Scripts API.⁠^{[5]BigCommerce Dev Center. Scripts API}
• La plantilla. La ficha la pinta el código de la aplicación. En la rama de desarrollo de Catalyst que leímos el 7 de octubre de 2026, la ficha toma el título del título SEO del producto o, si no hay, de su nombre; la descripción, de la meta description o, si no hay, de los primeros 150 caracteres de la descripción. Pinta un bloque Product con el nombre, la URL, la descripción, la marca, las valoraciones, la imagen, el SKU, el GTIN, el MPN y una oferta, y los custom fields salen en las especificaciones de la ficha, no en el bloque.⁠^{[22]BigCommerce en GitHub. bigcommerce/catalyst, rama canary: la ficha de producto (core/app/[locale]/(default)/product/[slug]/)}

La comprobación es la misma del paso 5, con más motivo: en Catalyst, lo que el código no pinta no existe, y la versión que despliega tu agencia puede no ser la que leímos nosotros.

Lo que hemos probado

Lo que comprobamos desde fuera, el 7 de octubre de 2026

Desde un ordenador nuestro, sin acceso a ningún panel, leímos el código de Cornerstone 6.22.0 y de Catalyst en GitHub, y pedimos una ficha de la tienda de demostración de BigCommerce, cornerstone-light-demo.mybigcommerce.com, que es de la propia plataforma.

• Dos bloques, un Product. La ficha respondió con un 200 y dos bloques application/ld+json: un BreadcrumbList y un Product. El Product no lleva @id y su oferta tenía como fecha de validez del precio el 7 de octubre de 2027, un año después de nuestra petición, como calcula la plantilla.
• Siete regiones, ningún widget. El HTML declaraba siete regiones con data-content-region, entre ellas las dos de la ficha, product_below_price y product_below_content,, y ningún data-widget-id: los huecos estaban, vacíos.
• Una fecha que no es ISO. La reseña del bloque Product lleva como fecha de publicación «2015 Dec 15th». Schema.org define el tipo Date como una fecha en formato ISO 8601,⁠^{[23]Schema.org. Date} y esa cadena no lo es. Es la tienda de demostración, no la tuya, pero es un buen motivo para leer tu marcado y no darlo por bueno.
• Sin meta description. El HTML de esa ficha no tenía etiqueta <meta name="description">.

La prueba en una tienda Stencil

• Preparación. Un producto ficticio, marcado como tal, con SKU, GTIN, título SEO, meta description y dos custom fields, uno de texto y uno con HTML en el valor. Se guarda el código fuente de su ficha antes de empezar, como línea base.
• Cinco caminos. (1) El custom field: ¿sale en la ficha? ¿y en el JSON-LD? (2) Un widget de HTML en Page Builder con un bloque application/ld+json, guardado sin publicar y después publicado. (3) Un widget por la Widgets API con entity_id del producto, primero sin status y después en active, con la petición y la respuesta de la API. (4) Un script de Script Manager con un bloque application/ld+json pegado en el pie, en la categoría de esenciales y después en la de analítica, con el banner de cookies activado y sin aceptar nada. (5) Si el revisor lo quiere, el mismo producto en un canal de Catalyst.
• Por cada camino. Si aparece en el código fuente (con el fragmento literal), cuánto tardó en aparecer, qué detecta la Prueba de resultados enriquecidos con la URL y, si la tienda está verificada en Search Console, «Ver página rastreada».
• Capturas. El código fuente de la ficha con la región, el data-widget-id y los bloques de datos estructurados (la del bloque de imagen del paso 5), y la Prueba de resultados enriquecidos, cada una con su fecha.

Probado en: tienda, tema y versión, variante, canal, fecha.

Los límites, tal cual: una tienda, un tema, una versión, un canal y una fecha. El comportamiento de la plataforma y de los temas cambia con cada versión.

Cuando lo publica Clione

Clione publica en BigCommerce por el camino del paso 3: su grafo de datos estructurados se publica con la Widget API y se renderiza en el servidor, con un nodo Product con un @id estable al lado del que ya pinta el tema, en lugar de duplicarlo. Nada llega a la tienda hasta que pulsas Push, y después Clione pide la ficha publicada y te dice, señal por señal, qué se pintó y qué no.