# Widget de BigCommerce: qué es y cómo se coloca

> Qué es un widget de BigCommerce, cómo se combinan plantilla, región y placement en la Widgets API, y cómo comprobar que sale en el HTML de tu tienda.

URL: https://clione.ai/es/glosario/widget-bigcommerce/
Lang: es

«Widget» se usa para casi cualquier caja incrustada en una web. Aquí es un objeto concreto de BigCommerce: **la pieza con la que una app o una agencia mete contenido en las páginas de un tema [Stencil](/es/glosario/stencil/) sin editar los archivos del tema**. Un banner, un bloque de preguntas frecuentes o los [datos estructurados](/es/glosario/datos-estructurados/) de una ficha pueden llegar así. Para una tienda importa por una razón práctica: si el widget no tiene una región donde caer, o su _placement_ está inactiva, el contenido existe en el panel y no existe en la página.

## Cómo funciona

La Widgets API sirve para crear unidades de contenido y colocarlas por programa en páginas concretas de una tienda BigCommerce. Ese contenido puede ser HTML, CSS y JavaScript, y se configura con variables de Handlebars.[^bc-widgets] La documentación lo reparte en cinco conceptos:[^bc-widgets]

| Concepto                                | Qué es                                                                                                                                                              |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plantilla de widget (_widget template_) | HTML con Handlebars que define la estructura del widget. Se reutiliza para crear varios widgets                                                                     |
| Widget                                  | Una configuración más el identificador (UUID) de su plantilla                                                                                                       |
| Configuración                           | El JSON con el contenido que la plantilla pinta, hasta 64 KB                                                                                                        |
| Región                                  | Un hueco declarado en los archivos del tema Stencil con `{{{region name="..."}}}`. Las que terminan en `--global` se muestran en todo el sitio |
| _Placement_                             | Decide en qué región va el widget y en qué orden                                                                                                                    |

Los widgets **se renderizan como parte del HTML de la tienda**. En la página se reconocen por dos atributos, `data-content-region` en la región y `data-widget-id` en el widget.[^bc-widgets]

La _placement_ es donde se decide casi todo. Se crea con una petición `POST` a `/v3/content/placements` y solo exige dos campos: `template_file`, la plantilla de página a la que apunta, y `widget_uuid`, el widget.[^bc-placement] Los demás afinan:[^bc-placement]

- `entity_id` limita la _placement_ a una página concreta: el ID del producto en una ficha, el de la categoría en una categoría. La portada no lo admite. Según la documentación, el identificador puede ser de un producto, una marca, una categoría o una página.[^bc-widgets]
- `region` y `sort_order` dicen en qué región va y en qué posición, si hay varios widgets en la misma.
- `channel_id` elige el canal; si no lo indicas, usa el primero que se creó en la tienda.
- `status` puede ser `active` o `inactive`, y **por defecto es `inactive`**.

Las _placements_ con región aparecen en Page Builder; las que no tienen región necesitan que se configure el diseño directamente.[^bc-placement] Las plantillas de página posibles incluyen `pages/product`, `pages/category` y `pages/home`, entre otras.[^bc-placements-course]

Y hay límites por tienda: 100.000 widgets, 1.000 plantillas propias por canal y 5.000 en total, **75 _placements_ por plantilla de página** y 10.000 _placements_ en total.[^bc-widgets] Si creas una _placement_ por producto, en un catálogo grande ese límite llega pronto.

## En una tienda

Un **ejemplo ficticio**: un widget con el [JSON-LD](/es/glosario/json-ld/) de un trípode, colocado solo en su ficha. La _placement_ se pediría así (el nombre de la región depende del tema; este es inventado):

```json
{
  "widget_uuid": "00000000-0000-4000-8000-000000000001",
  "template_file": "pages/product",
  "entity_id": "112",
  "region": "ficha_inferior",
  "sort_order": 1,
  "status": "active"
}
```

Y en el HTML de la ficha 112 aparecería algo parecido a esto (simplificado):

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

Que el marcado quede en el cuerpo y no en la cabecera 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 procesa cuando lo inyectan widgets del gestor de contenidos.[^google-structured-data] Clione usa este mismo camino: en BigCommerce, su grafo de datos estructurados se publica con la Widget API y se renderiza en el servidor.


**Crear el widget no es publicarlo.** Un widget sin _placement_ no sale en ninguna página, y una _placement_ creada sin `status` se queda en `inactive`, que es el valor por defecto.[^bc-placement] Además, la región tiene que existir en los archivos del tema que usa la tienda, porque las regiones son huecos que declara el tema.[^bc-widgets] Antes de buscar el fallo en la plantilla, comprueba esas dos cosas.


## Cómo comprobarlo

1. **Consulta las regiones del tema** con el endpoint de regiones de la Widgets API, para la plantilla de página que te interesa. Si la región que usa tu _placement_ no está en la lista, el widget no tiene dónde caer.[^bc-widgets]
2. **Revisa la _placement_**: `status` en `active`, el `template_file` correcto, el `entity_id` del producto o la categoría que esperas y el canal adecuado.[^bc-placement]
3. **Abre la página y su código fuente** (Ctrl+U en Chrome) y busca `data-widget-id`. Si no aparece, el problema está en la _placement_ o en la región, no en la plantilla.[^bc-widgets]
4. **Si el widget publica datos estructurados**, pasa la URL por la [prueba de resultados enriquecidos](/es/glosario/prueba-de-resultados-enriquecidos/) o por un [validador de schema](/es/glosario/validador-de-schema/).
5. **Cuenta tus _placements_** por plantilla de página antes de escalar a todo el catálogo: el límite es 75 por plantilla.[^bc-widgets]

## Concepto cercano: app embed de Shopify

El equivalente más cercano en Shopify es el [app embed de Shopify](/es/glosario/app-embed-shopify/). Los dos meten código en la tienda sin editar el tema, pero se colocan de forma distinta. Shopify inserta un app embed **antes del cierre de `</head>` o de `</body>`**, según el destino que declare el bloque, y el comerciante lo enciende en el editor de temas; tras instalar la app viene apagado.[^shopify-tae-config] Un widget de BigCommerce, en cambio, va a la región y a la página que diga su _placement_, que se crea por API, y puede limitarse a una sola ficha con `entity_id`.[^bc-placement] En los dos casos, lo que de verdad cuenta es lo que sale en el HTML de la página, y eso se comprueba abriéndola.

La guía [del widget a la página publicada](/es/guias/widget-bigcommerce-pagina-publicada/) sigue el camino completo en BigCommerce, y la [ruta de publicación por plataforma](/es/aprender/publicacion-por-plataforma/) ordena el resto de términos.