---
title: "Headless and custom storefronts"
description: "A guide to running the SureBright SDK outside the Shopify theme app embed: declaring your store and platform, giving the SDK page context, keeping cart line properties intact, and what fails when a step is skipped."
---

On a Shopify Online Store theme the SureBright app embed loads the SDK, tells it which store it is on, and hands it a cart it already knows how to read. On a headless build (Hydrogen, Shopyflow on Webflow, or your own front end) none of that is given. You own the script tag, the cart, and the page, so you have to supply what the embed would have supplied. This guide walks through those pieces in order and ends with what breaks when one is missing.

The exact attributes, globals and line-item properties are specified in the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection); this page explains how they fit together and does not repeat the field tables.

## Which path are you on

| Storefront | Adapter the SDK uses | What you need to do |
| --- | --- | --- |
| Shopify Online Store theme | `shopify` | Nothing here. Turn on the app embed; see [Storefront setup](/shopify/storefront-setup). |
| Shopify Hydrogen / Remix | `shopify-hydrogen` | Everything on this page, plus the Hydrogen loader and cart-action requirements in [SDK Installation](/frontend-widget-integration/frontend-widget-kit/sdk-installation#shopify-hydrogen-and-other-headless-shopify-builds). |
| Shopyflow (Shopify on Webflow) | `shopify-shopyflow` | Steps 1, 2 and 4 below. The SDK reads Shopyflow's own globals for the rest. |
| Another headless Shopify front end | none yet | Talk to SureBright before building. The SDK can only drive carts it has an adapter for. |
| BigCommerce, WooCommerce | `bigcommerce`, `woocommerce` | Wired by the SureBright integration for that platform. |

`custom` is also accepted as a platform name, but that adapter reads no product data and has no cart, so no offer renders and nothing can be added. Use it only when SureBright asks you to.

## Step 1: declare the store and platform on the script tag

Load the script once per page and tell it who you are:

```html
<script id="sbsimxsdk" async
        src="https://cdn.surebright.com/sbsimxsdk.js"
        data-sb-store-id="your-store.myshopify.com"
        data-sb-platform="HYDROGEN"></script>
```

- `data-sb-store-id` is the store identifier SureBright gave you. For Shopify-backed storefronts that is the `*.myshopify.com` domain, not your public hostname. The SDK does not keep a list of customer domains, so it cannot work this out from the URL.
- `data-sb-platform` is matched case-insensitively against `SHOPIFY`, `HYDROGEN`, `SHOPYFLOW`, `BIGCOMMERCE`, `WOOCOMMERCE` and `CUSTOM`. Setting `window.__SUREBRIGHT_PLATFORM__` before the script (lower-case names such as `shopify-hydrogen`) does the same thing and is checked next.

The SDK reads these from `document.currentScript` while it executes, then falls back to the first `<script>` element on the page that carries `data-sb-store-id`. That fallback is what makes tag managers and bundlers work, so keep the attributes on the tag that actually loads the file.

If you declare nothing, detection runs heuristics: `window.Shopify.shop` first, then Shopyflow's global, then a Hydrogen score. The Hydrogen score adds 40 for a `cartFormInput` with Hydrogen's `{action, inputs.lines}` shape, 30 for a `gid://shopify/` merchandise id inside it, 25 for `data-hydrogen`, `data-remix` or `data-shopify-hydrogen` attributes, 20 for `.data` loader links or an `entry.client` script, 15 for Shopify URL patterns without `window.Shopify`, and 10 for Shopify CDN assets without `window.Shopify`; 40 or more means Hydrogen. A page without a product form has only the weaker signals to go on, so a declared platform is always safer than a guess. Detection retries for 15 seconds and then stops with `[SB] Platform detection timed out`.

## Step 2: tell the SDK which page it is on

Two things are read from the page itself.

**Page type** comes from the path, per adapter. For Hydrogen and Shopyflow: `/products/` is a product page (Shopyflow uses its configured `productPagePath`), `/cart` the cart, `/collections/` a collection, `/checkout` checkout, and `/thank-you`, `/thank_you` or `/orders/` the post-purchase page. Keep these conventional paths or the matching surfaces will not mount.

**Design context** is optional. The Shopify embed writes `window.__SUREBRIGHT_PAGE__ = { themeId, templateSuffix }` from Liquid so SureBright can serve a theme- or template-specific design. On a headless build nothing writes it. If SureBright has set up design targeting for your store, set it yourself before the script runs; otherwise leave it out and the store's default design is used. The values are sent as `themeId` and `pageTemplate` on the configuration request and become part of the configuration cache key, so a wrong value shows the wrong design, not an error. `window.Shopify.theme.id` and `<body data-sb-page-template>` are read as fallbacks when they exist.

## Step 3: give the SDK the product and the cart

The SDK needs to know which variant the shopper is looking at, read the cart, and write protection lines to it.

**Hydrogen.** Keep the skeleton template's conventions: the hidden `input[name="cartFormInput"]` in the product form, the `/cart.data` and `/products/{handle}.data` loaders, and a cart action that accepts `LinesAdd`, `LinesUpdate` and `LinesRemove` with line `attributes`. These are listed step by step in [SDK Installation](/frontend-widget-integration/frontend-widget-kit/sdk-installation#shopify-hydrogen-and-other-headless-shopify-builds). The SDK's own requests carry an `X-SB-Internal: 1` header so they are not mistaken for shopper adds.

**Shopyflow.** The SDK reads `window.Shopyflow`: `config.shopifyDomain` and `config.token` to call the Storefront API directly, `currentProducts` for the product on the page, and `_cart` or `localStorage['_sf-cart-id']` for the cart id. The variant a button sells is read from its `sf-add-to-cart` attribute (a variant GID), and the product from `sf-product`; on a page that embeds several products the SDK resolves the product from the button that was clicked, not from the page-global list. Shopyflow owns `window.fetch`, so the SDK does not try to rewrite your add-to-cart request. It lets the native add run and then writes the protection line into the same Storefront cart with `cartLinesAdd`, polling briefly for the cart id when the native add is the one that creates the cart. Keep the attributes above in place and do not rename the cart-id storage key.

In both cases the protection product is a real variant in your Shopify catalogue, so the Storefront API accepts it like any other line. If your storefront filters which variants may be added to the cart, allow SureBright's protection products through.

## Step 4: carry the `_sb*` line properties to the order

Every protection line the SDK writes carries properties (Shopify line-item properties, Storefront API line `attributes`) that start with `_sb`, plus `_variantId` and, for bundles, `_bundle*` keys. They are the only link between the line the shopper paid for and the quote they saw.

- Pass `attributes` through unchanged in your cart action, your cart UI state, and any cart transform or checkout customisation.
- Do not re-key or merge lines. Each add carries a unique `_sbAddedAt` so two adds of the same plan stay separate; merging them hides a quantity change from SureBright.
- Do not render a "remove" control that rebuilds the cart without attributes.

What SureBright reads from them, and what happens to an order that arrives without `_sbQuoteId` or `_sbQuoteItemId`, is in [Cart line-item properties](/frontend-widget-integration/frontend-widget-kit/javascript-injection#cart-line-item-properties). Shopify's checkout extensions read the same properties to show the **Protected** badge, so dropping them also degrades checkout; see [Checkout extensions](/shopify/checkout-extensions).

## Step 5: let cart sync see the cart

The SDK keeps protection quantities aligned with the products they cover and removes protection whose product left the cart. On Hydrogen and Shopyflow it treats cart reads as unreliable, because a headless cart briefly under-reports its lines while a mutation is in flight. A removal that depends on a missing product is therefore executed only when two consecutive reads, about 2.5 seconds apart, agree. If your cart loader returns partial carts for longer than that, or your fetch wrapper swallows `/cart.data` responses, sync either stalls or acts on stale data. Details in [Client-side cart sync](/frontend-widget-integration/frontend-widget-kit/cart-sync).

## Step 6: analytics

Every analytics event carries the store id. Without `data-sb-store-id` the Hydrogen adapter reports an empty store id and the SDK drops every event before sending, so the merchant portal shows no impressions or conversions for the storefront. Consent gating uses Shopify's Customer Privacy API, which only exists on Online Store themes; on a headless build the SDK records as soon as the shopper interacts. If your storefront has its own consent manager, tell SureBright. See [Analytics and consent](/frontend-widget-integration/frontend-widget-kit/analytics-and-consent).

## What breaks when a step is skipped

| Missing | Effect |
| --- | --- |
| `data-sb-store-id` (headless) | Store id is empty. No configuration loads, no offer renders, every analytics event is dropped. Debug log shows the config request failing. |
| `data-sb-platform` and `__SUREBRIGHT_PLATFORM__` | The SDK guesses. A wrong guess (for example `shopify` on a Hydrogen page) means cart reads fail and no offer renders; a low Hydrogen score means detection times out after 15 seconds. |
| `cartFormInput` (Hydrogen) | The SDK cannot tell which variant is selected, so it quotes the wrong variant or nothing. |
| `attributes` passed through the cart action | Lines reach the order without `_sbQuoteId`. No contract is created; an order that contains only such a line is refunded and cancelled as fraudulent. |
| Conventional paths (`/products/`, `/cart`, `/thank-you`) | Surfaces for those pages never mount. |
| `__SUREBRIGHT_PAGE__` on a store with design targeting | The default design renders instead of the targeted one. |
| Reliable `/cart.data` or Storefront cart reads | Cart sync defers removals indefinitely or, worse, acts on a half-written cart. |

## Verify

1. Open a product page with `?sb_debug` and confirm a `[SB] [PLATFORM]` line names the adapter you expect, followed by a `[SB] [CONFIG]` line that loads the store configuration.
2. Add a product with a plan and inspect the cart (Hydrogen: `/cart.data`; Shopyflow: the Storefront cart). The protection line must show `_sbQuoteId`, `_sbQuoteItemId` and `_variantId`.
3. Change the product quantity in your cart UI and confirm the protection line follows within a few seconds.
4. Place a test order and ask SureBright to confirm a contract was created for it.

When the storefront is ready, tell SureBright. Placements, design and which surfaces are on are finished on SureBright's side before the offer goes live for shoppers.

**See also:** [Building your own offer](/merchant-portal/widget-options#building-your-own-offer), [Accessibility](/merchant-portal/widget-options#accessibility).
