¿Qué es un widget de BigCommerce (Widgets API)?

«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 sin editar los archivos del tema. Un banner, un bloque de preguntas frecuentes o los 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.⁠^{[1]BigCommerce Dev Center. Widgets API} La documentación lo reparte en cinco conceptos:⁠^{[1]BigCommerce Dev Center. Widgets API}

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.⁠^{[1]BigCommerce Dev Center. Widgets API}

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.⁠^{[2]BigCommerce API Reference. Create Placement} Los demás afinan:⁠^{[2]BigCommerce API Reference. Create 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.⁠^{[1]BigCommerce Dev Center. Widgets API}
• 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.⁠^{[2]BigCommerce API Reference. Create Placement} Las plantillas de página posibles incluyen pages/product, pages/category y pages/home, entre otras.⁠^{[3]BigCommerce Developer Learning. Placements}

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.⁠^{[1]BigCommerce Dev Center. Widgets API} 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 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):

{
  "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):

<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.⁠^{[4]Google Search Central. Introduction to structured data markup in Google Search} Clione usa este mismo camino: en BigCommerce, su grafo de datos estructurados se publica con la Widget API y se renderiza en el servidor.

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.⁠^{[1]BigCommerce Dev Center. Widgets API}
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.⁠^{[2]BigCommerce API Reference. Create 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.⁠^{[1]BigCommerce Dev Center. Widgets API}
4. Si el widget publica datos estructurados, pasa la URL por la prueba de resultados enriquecidos o por un 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.⁠^{[1]BigCommerce Dev Center. Widgets API}

Concepto cercano: app embed de Shopify

El equivalente más cercano en Shopify es el app embed de 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.⁠^{[5]Shopify Dev Docs. Configure theme app extensions} 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.⁠^{[2]BigCommerce API Reference. Create 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 sigue el camino completo en BigCommerce, y la ruta de publicación por plataforma ordena el resto de términos.