What is a BigCommerce widget (Widgets API)?

"Widget" gets used for almost any box embedded in a website. Here it is one specific BigCommerce object: the piece an app or an agency uses to put content on the pages of a Stencil theme without editing the theme's files. A banner, a block of frequently asked questions or the structured data of a product page can arrive that way. For a store it matters for a practical reason: if the widget has no region to land in, or its placement is inactive, the content exists in the control panel and does not exist on the page.

How it works

The Widgets API is for creating units of content and placing them programmatically on specific pages of a BigCommerce store. That content can be HTML, CSS and JavaScript, and it is configured with Handlebars variables.⁠^{[1]BigCommerce Dev Center. Widgets API} The documentation breaks it into five concepts:⁠^{[1]BigCommerce Dev Center. Widgets API}

Widgets render as part of the store's HTML. On the page they are recognized by two attributes, data-content-region on the region and data-widget-id on the widget.⁠^{[1]BigCommerce Dev Center. Widgets API}

The placement is where almost everything is decided. It is created with a POST request to /v3/content/placements and requires only two fields: template_file, the page template it points to, and widget_uuid, the widget.⁠^{[2]BigCommerce API Reference. Create Placement} The rest fine-tune it:⁠^{[2]BigCommerce API Reference. Create Placement}

• entity_id limits the placement to one specific page: the product ID on a product page, the category ID on a category. The home page does not accept it. According to the documentation, the identifier can belong to a product, a brand, a category or a page.⁠^{[1]BigCommerce Dev Center. Widgets API}
• region and sort_order say which region it goes in and in what position, if there are several widgets in the same one.
• channel_id picks the channel; if you do not give one, it uses the first channel created in the store.
• status can be active or inactive, and it defaults to inactive.

Placements with a region show up in Page Builder; those without a region need the layout to be configured directly.⁠^{[2]BigCommerce API Reference. Create Placement} The possible page templates include pages/product, pages/category and pages/home, among others.⁠^{[3]BigCommerce Developer Learning. Placements}

And there are per-store limits: 100,000 widgets, 1,000 custom templates per channel and 5,000 in total, 75 placements per page template and 10,000 placements in total.⁠^{[1]BigCommerce Dev Center. Widgets API} If you create one placement per product, on a large catalog you hit that limit soon.

In a store

A fictitious example: a widget with a tripod's JSON-LD, placed only on its product page. The placement would be requested like this (the region name depends on the theme; this one is made up):

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

And in the HTML of product page 112 something like this would appear (simplified):

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

That the markup ends up in the body and not in the head is not a problem for Google: JSON-LD goes in a <script> tag inside the <head> or the <body>, and Google also processes it when content management widgets inject it.⁠^{[4]Google Search Central. Introduction to structured data markup in Google Search} Clione uses this same path: on BigCommerce, its structured data graph is published with the Widget API and rendered on the server.

How to check it

1. Look up the theme's regions with the Widgets API's regions endpoint, for the page template you care about. If the region your placement uses is not on the list, the widget has nowhere to land.⁠^{[1]BigCommerce Dev Center. Widgets API}
2. Review the placement: status set to active, the right template_file, the entity_id of the product or category you expect and the right channel.⁠^{[2]BigCommerce API Reference. Create Placement}
3. Open the page and its source code (Ctrl+U in Chrome) and search for data-widget-id. If it does not appear, the problem is in the placement or the region, not in the template.⁠^{[1]BigCommerce Dev Center. Widgets API}
4. If the widget publishes structured data, run the URL through the Rich Results Test or a schema markup validator.
5. Count your placements per page template before scaling to the whole catalog: the limit is 75 per template.⁠^{[1]BigCommerce Dev Center. Widgets API}

Related concept: Shopify app embed

The closest equivalent on Shopify is the Shopify app embed. Both put code in the store without editing the theme, but they are placed differently. Shopify inserts an app embed before the closing </head> or </body>, depending on the target the block declares, and the merchant turns it on in the theme editor; after the app is installed it starts off.⁠^{[5]Shopify Dev Docs. Configure theme app extensions} A BigCommerce widget, by contrast, goes in the region and on the page its placement says, which is created through the API, and it can be limited to a single product page with entity_id.⁠^{[2]BigCommerce API Reference. Create Placement} In both cases, what really counts is what comes out in the page's HTML, and you check that by opening it.

The guide from widget to published page follows the whole path on BigCommerce, and the publishing by platform reading path puts the rest of the terms in order.