# Del widget a la ficha publicada en BigCommerce, paso a paso

> Cómo llega un dato a la ficha publicada de BigCommerce: plantilla Stencil, widget de Page Builder, Script Manager o Catalyst, y el HTML que lo prueba.

URL: https://clione.ai/es/guias/widget-bigcommerce-pagina-publicada/
Lang: es

Has rellenado los [custom fields](/es/glosario/custom-fields-bigcommerce/) 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](/es/glosario/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](/es/glosario/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**.[^bc-stencil-stack] Es [renderizado del lado del servidor](/es/glosario/ssr/): 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](/es/glosario/catalyst/), el frontend _headless_ de BigCommerce, cambia las reglas de los tres:

| Camino                | Dónde lo configuras                                                                                          | Qué lo pone en la página                                                                     | Se pierde si…                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| La plantilla del tema | El producto, en el panel o por la [API de catálogo](/es/glosario/api-de-catalogo/); la plantilla, en el tema | Handlebars, en el servidor[^bc-stencil-stack]                                                | La plantilla no lo pinta                                                                                                   |
| Un widget             | Page Builder, o la [Widgets API](/es/glosario/widget-bigcommerce/) desde una aplicación                      | El HTML de la tienda, dentro de una región del tema[^bc-widgets]                             | No hay región, la _placement_ está inactiva o el cambio no se publicó[^bc-placement][^bc-page-builder-help]                |
| Un script             | Script Manager, o la Scripts API desde una aplicación                                                        | Los huecos de scripts de la cabecera y del pie del tema[^bc-scripts]                         | El tema no tiene esos huecos, o el comprador rechaza su categoría en el banner de cookies[^bc-scripts][^bc-script-manager] |
| Catalyst              | El código del frontend                                                                                       | La aplicación de Next.js, que pide los datos a la API de escaparate en GraphQL[^bc-catalyst] | El código no lo pinta                                                                                                      |

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](/es/glosario/meta-title/) y la [_meta description_](/es/glosario/meta-description/) de cada producto se editan en el propio producto, en su sección SEO.[^bc-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**.[^bc-api-custom-field]
- **Los identificadores.** [SKU](/es/glosario/sku/), [MPN](/es/glosario/mpn/) y [GTIN](/es/glosario/gtin/). En Cornerstone, el bloque de [datos estructurados](/es/glosario/datos-estructurados/) escribe cada uno solo si el producto lo tiene, como verás en el paso 2.[^cornerstone-622]

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`.[^bc-frontmatter]

En Cornerstone 6.22.0, el tema por defecto, la ficha se monta así:[^cornerstone-622]

- `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](/es/glosario/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:


```handlebars
{{#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](/es/glosario/schema-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.[^cornerstone-622] Y dos ausencias: **el nodo no lleva [`@id`](/es/glosario/id-json-ld/) 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**.[^bc-lab-custom-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».[^bc-page-builder-help] Por debajo, Page Builder mete los widgets con la Widgets API, el mismo mecanismo que usan los widgets de la propia plataforma.[^bc-page-builder-dev]

**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.[^bc-widgets] Al crearla, cuatro campos deciden si la ves:[^bc-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,[^bc-regions] y en Cornerstone 6.22.0 la ficha tiene dos, `product_below_price` y `product_below_content`.[^cornerstone-622] El límite que llega pronto en un catálogo grande: **75 _placements_ por plantilla de página**.[^bc-widgets]

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.[^bc-widgets] 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.[^bc-third-party-widgets]

En el HTML, la región y el widget se reconocen por dos atributos; la _placement_ no deja ninguna marca.[^bc-widgets] Esto es lo que buscas en la ficha (ejemplo ficticio, simplificado):


```html
<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](/es/glosario/resultados-enriquecidos/).[^google-structured-data]

## 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.[^bc-script-manager] (Catalyst lee sus scripts a su manera, como verás al final.) Cada script se configura con:[^bc-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**.[^bc-scripts] 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>`:[^cornerstone-622]


```handlebars
    {{{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.[^bc-script-manager]
- **En local no se ven.** Si desarrollas el tema con Stencil CLI, los scripts creados con la Scripts API no se pintan.[^bc-scripts]
- **El banner de cookies decide.** Con el banner activo, el comprador puede rechazar categorías de scripts; de los esenciales no se puede salir.[^bc-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.[^google-js-sd]

## 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.[^bc-widgets]
- **`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](/es/glosario/rastreador/) que renderiza; la guía sobre [qué ve un rastreador de IA](/es/guias/que-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](/es/glosario/prueba-de-resultados-enriquecidos/)** con la URL, no pegando el código, porque con el código hay límites de JavaScript.[^google-js-sd] Entra como móvil salvo que elijas otra cosa y dice qué tipos de resultados enriquecidos encuentra, con sus errores y sugerencias.[^google-rrt]
- **La inspección de URLs de [Search Console](/es/glosario/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.[^gsc-url-inspection]


Si lo que quieres es revisar el marcado en sí, está la guía para [auditar los datos estructurados de una ficha](/es/guias/auditar-ficha-de-producto/). Y conviene no confundir los dos verbos: [validar el marcado no es lo mismo que verificar que se publica](/es/comparativas/validar-vs-verificar/). Lo segundo, comprobar en la página viva que cada señal está, es la [verificación de publicación](/es/glosario/verificacion-de-publicacion/).


**Guardar no es publicar, y crear no es colocar.** En Page Builder, un cambio guardado no se ve hasta que se publica.[^bc-page-builder-help] Por API, un widget sin _placement_ no sale en ninguna página, y una _placement_ creada sin `status` nace `inactive`.[^bc-widgets][^bc-placement] En Script Manager, el cambio tarda unos segundos en salir de la caché.[^bc-script-manager] Antes de buscar el fallo en el código del widget o del script, abre la ficha publicada y busca `data-widget-id` o el script: si no están, el problema está en la publicación, no en el contenido.


## 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.[^bc-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.[^bc-widgets] 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.[^bc-catalyst-features]
- **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.[^bc-catalyst-scripts] Los scripts con expresiones Handlebars hechos para Stencil no funcionan en Catalyst,[^bc-catalyst-features] y las versiones anteriores a la 1.1 no pintan los de la Scripts API.[^bc-scripts]
- **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**.[^gh-catalyst-pdp]

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](/es/glosario/schema-org/) define el tipo Date como una fecha en formato ISO 8601,[^schema-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.

| Camino                         | Variante                       | En el código fuente | Tiempo hasta aparecer | Prueba de resultados enriquecidos |
| ------------------------------ | ------------------------------ | ------------------- | --------------------- | --------------------------------- |
| Custom field                   | En la ficha                    |                     |                       |                                   |
| Custom field                   | En el JSON-LD                  |                     |                       |                                   |
| Widget de HTML en Page Builder | Guardado, sin publicar         |                     |                       |                                   |
| Widget de HTML en Page Builder | Publicado                      |                     |                       |                                   |
| Widget por la Widgets API      | _Placement_ sin `status`       |                     |                       |                                   |
| Widget por la Widgets API      | _Placement_ `active`           |                     |                       |                                   |
| Script Manager, pie            | Esencial, sin aceptar cookies  |                     |                       |                                   |
| Script Manager, pie            | Analítica, sin aceptar cookies |                     |                       |                                   |

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.