JavaScript API Reference
What the SureBright storefront SDK exposes on the page: window.SureBright, the selection-change callback, DOM events, cart line-item properties, platform and page overrides, and debugging switches.
The SureBright storefront SDK (sbsimxsdk*.js) starts itself as soon as the script runs. You do not call an init function, pass a store id, or wait for a callback. This page lists everything the script puts on window and what your own code can rely on.
Only the items on this page are a supported integration surface. Everything else in the bundle (internal event names, class names, element internals) can change between SDK releases without notice.
Lifecycle#
When the script executes it:
Sets
window.__SUREBRIGHT__ = trueand returns early if that flag is already set, so loading the script twice is harmless.Creates
window.SureBright(see below).Waits for
document.readyStateto reachinteractive, then detects the storefront platform. Detection retries with back-off for up to 15 seconds; if no supported platform is found it logs[SB] Platform detection timed out after 15s - store may not be supportedand stops.Loads the store's widget configuration from SureBright and renders whatever surfaces are enabled for the store and the current page.
The script is safe to include on every page. Which widgets render, and where, is decided by the store configuration SureBright maintains, not by anything in the page. See Placements.
window.SureBright#
interface SureBright {
onSelectionChange(handler: (change: SelectionChange) => void): () => void;
/** @deprecated No-op kept for backwards compatibility. */
initialize(): Promise<void>;
}onSelectionChange(handler)#
Registers a handler that runs whenever the shopper selects, switches, or deselects a protection plan on any SureBright surface. Returns a function that removes the handler.
const unsubscribe = window.SureBright.onSelectionChange(function (change) {
if (change.action === "selected" && change.pricing) {
// The shopper picked a plan. Show product + protection.
render(change.pricing.totalPrice, change.pricing.currency);
} else if (change.pricing) {
// The shopper removed protection. Fall back to the product price.
render(change.pricing.basePrice, change.pricing.currency);
}
});
// Later, if you need to stop listening:
unsubscribe();Notes:
Handlers are stored in a
Set, so registering the same function twice has no effect.A handler that throws is caught and logged; it does not break the widget or other handlers.
The SDK never edits your page's price elements. If you want the displayed price to include protection, do it in your handler.
The script is
defer/async-loaded, sowindow.SureBrightmay not exist when your inline code runs. Guard for it or register after the script'sloadevent.
SelectionChange payload#
action'selected' | 'deselected'requiredWhat the shopper did. Choosing the "no coverage" / decline card is reported as deselected.
sourcestringrequiredThe surface the change came from. Values the SDK emits: pdp (product page offering, including the plan modal opened from it), quickview, cart (plan modal opened from a cart call-to-action), checkout, postPurchase, registration, shippingInsurance.
quoteobject | nullThe selected plan. null on deselected, and on surfaces that do not carry a full quote. Core fields are listed here; additional fields may be present depending on the surface.
productobject | nullThe covered product, or null when the SDK has no product context (for example on checkout and shipping-protection surfaces).
pricingobject | nullConvenience totals. null whenever product is null.
initialize() (deprecated)#
Older integrations called SureBright.initialize({ storeId }, callback) and waited for the callback. The current SDK ignores the arguments and returns Promise.resolve(). It exists only so that old code does not throw. Remove the call when you can; the SDK is already running by the time your code can reach it.
SureBright.getCartItems(...) no longer exists. Read the cart through your platform's own cart API and look for the line-item properties described below.
sb-widget-event DOM events#
Every SureBright custom element communicates with the SDK core by dispatching a CustomEvent named sb-widget-event with bubbles: true and composed: true, so it is observable on document. event.detail.type identifies the interaction; some events carry extra fields (for example detail.quote, detail.enabled, detail.checked).
document.addEventListener("sb-widget-event", function (event) {
console.log(event.detail.type, event.detail);
});Types dispatched by the current bundle include:
The product-registration page element uses detail.action and detail.data instead of detail.type.
This event is the SDK's internal wiring. It is documented so you can recognise it in DevTools, not as a stable API. Use onSelectionChange for anything you ship.
Cart line-item properties#
When the SDK adds protection to the cart it writes the protection product as its own line item and attaches properties to that line. On Shopify these are line-item properties (keys starting with _ are hidden from the shopper); on Hydrogen they are cart line attributes. Your storefront must carry these properties unchanged from the cart to the order. They are how SureBright ties the order back to the quote the shopper saw.
Product protection line#
Protection added for a component of a bundle additionally carries _bundleParentVariantId, _bundleParentProductId, _isBundleComponentPolicy ("true") and _componentQuantity.
Shipping protection line#
What happens when properties are missing#
SureBright's order webhook reads _sbQuoteId, _sbQuoteItemId, _variantId, _quotePlatform and _sbSessionTreatmentId from protection lines, and _sbQuoteId from shipping-protection lines.
A protection line without
_sbQuoteIdcannot be matched to a quote, so no contract is created for it.If an order contains only a SureBright protection line and that line is missing
_sbQuoteIdor_sbQuoteItemId, the order is treated as fraudulent: SureBright refunds it and cancels it automatically.If the quote's country does not match the order's country, order processing fails.
So: never strip, rename, or re-key these properties in cart transforms, discount apps, or custom checkout flows.
Platform and page overrides#
window.__SUREBRIGHT_PLATFORM__#
Set this before the SDK script runs to skip auto-detection:
<script>window.__SUREBRIGHT_PLATFORM__ = "shopify-hydrogen";</script>Accepted values: shopify, shopify-hydrogen, shopify-shopyflow, bigcommerce, woocommerce, custom.
Detection order: a data-sb-platform attribute on the SDK <script> tag (case-insensitive, same names) is checked first, then window.__SUREBRIGHT_PLATFORM__, then heuristics (window.Shopify.shop, Shopyflow globals, Hydrogen markers such as input[name="cartFormInput"], window.BCData.store_hash, WooCommerce globals, <meta name="generator">, and script sources).
The script tag can also carry data-sb-store-id. The Hydrogen adapter uses it as the store id; without it the store id is empty and SureBright cannot load the store's configuration.
window.__SUREBRIGHT_PAGE__#
Tells the SDK which theme and page template is rendering so it can load theme- or template-specific widget configuration:
<script>
window.__SUREBRIGHT_PAGE__ = { themeId: "123456789", templateSuffix: "landing" };
</script>Both fields are optional strings (trimmed, truncated to 120 characters). Fallbacks: themeId from window.Shopify.theme.id, templateSuffix from <body data-sb-page-template="...">. Only set these if SureBright has configured a theme- or template-specific design for your store; otherwise the default configuration is used.
Debugging#
Log lines are prefixed [SB] [CATEGORY] (categories include INIT, CONFIG, PLATFORM, QUOTES, INTERCEPTOR, WIDGET, CART, SYNC, ANALYTICS, VARIANT). In the shipped bundle all levels, including warnings and errors, are silent unless debug mode is on. The SDK also keeps the last 100 log entries in memory for SureBright's own tooling; there is no public accessor.
window.__SB_DIAG__ is not created by the storefront SDK. It is populated by a separate diagnostic script that SureBright engineers paste into the console; you can ignore it.
Custom elements#
The SDK renders its UI as custom elements, each with an open shadow root, so your theme CSS does not leak in and the widget CSS does not leak out. Styling is controlled through the store's design configuration in SureBright, not by overriding these elements.
Elements the SDK inserts carry a data-sb-widget-surface attribute (for example quickview) and, for inline product offerings, data-sb-surface="embedded". Use these to detect the widget in your own scripts; do not move or restyle them.