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:

  1. Sets window.__SUREBRIGHT__ = true and returns early if that flag is already set, so loading the script twice is harmless.

  2. Creates window.SureBright (see below).

  3. Waits for document.readyState to reach interactive, 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 supported and stops.

  4. 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#

typescript
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.

javascript
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, so window.SureBright may not exist when your inline code runs. Guard for it or register after the script's load event.

SelectionChange payload#

action'selected' | 'deselected'required

What the shopper did. Choosing the "no coverage" / decline card is reported as deselected.

sourcestringrequired

The 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 | null

The 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 | null

The covered product, or null when the SDK has no product context (for example on checkout and shipping-protection surfaces).

pricingobject | null

Convenience 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).

javascript
document.addEventListener("sb-widget-event", function (event) {
  console.log(event.detail.type, event.detail);
});

Types dispatched by the current bundle include:

Surfacedetail.type
Product / quick-view offeringQUOTE_SELECTED, QUOTE_DESELECTED, LEARN_MORE_CLICKED, GATE_TOGGLED
Plan ("What's covered") modalWARRANTY_OFFERING_PROTECT_CLICKED, WARRANTY_OFFERING_DECLINE_CLICKED, WARRANTY_OFFERING_CLOSED
CartCART_CTA_CLICKED, BOTTOM_CART_CTA_TOGGLED, WARRANTY_PLAN_CHANGE_CLICKED, LINE_ITEM_BADGE_INFO_VIEWED
Checkout widgetCHECKOUT_WARRANTY_SELECTED, CHECKOUT_WARRANTY_DESELECTED
Shipping protectionSHIPPING_INSURANCE_TOGGLED, SHIPPING_INSURANCE_DIALOG_OPEN, SI_COVERAGE_LINK_CLICKED, SI_PROTECT_CLICKED, SI_DECLINE_CLICKED
Post-purchase modalPP_PLAN_SELECTED, PP_PLAN_DESELECTED, PP_PROTECT, PP_DECLINE, PP_NEXT, PP_BACK, PP_CLOSE

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#

PropertyValueNotes
ProductCovered product titleVisible to the shopper.
Terme.g. 2 YearsVisible to the shopper.
_variantIdCovered product's variant idLinks the protection line to the product line.
_sbQuoteIdQuote idRequired by the order webhook.
_sbQuoteItemIdSelected plan id within the quoteRequired by the order webhook.
_sbPriceVersionIdPrice versionWritten on every line; a fixed placeholder when the store has no versioned pricing.
_sbAddedAtDate.now() as a stringUsed by cart sync to tell lines apart.
_sbWarrantySourceWhich control added the planOnly when known.
_sbSessionTreatmentIdExperiment treatment idOnly when the store runs an experiment.
_lineItemKeyCovered cart line keyOnly on platforms that expose line keys.
_quotePlatformPricing channelOnly for non-standard quotes (for example post-purchase).
_sbPurchasedQuantityQuantity purchasedOnly when _quotePlatform is PLATFORM_POST_PURCHASE.

Protection added for a component of a bundle additionally carries _bundleParentVariantId, _bundleParentProductId, _isBundleComponentPolicy ("true") and _componentQuantity.

Shipping protection line#

PropertyValue
_sbQuotePlatformPLATFORM_SHIPPING_INSURANCE
_sbQuoteIdShipping quote id
_sbAddedAtDate.now() as a string
_sbWarrantySourceOnly when known
_sbSessionTreatmentIdOnly when the store runs an experiment

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 _sbQuoteId cannot 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 _sbQuoteId or _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:

html
<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:

html
<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#

SwitchEffect
?sb_debug in the URLTurns on console logging for this page load.
localStorage.setItem("sb_debug", "true")Turns on console logging for every page load until removed.
window.__SUREBRIGHT_DESTROY__()Tears down widgets, interceptors, and listeners created by the SDK. Reload the page to get them back.

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.

ElementWhere
sb-product-widgetProduct page and quick view offering
sb-warranty-offering-modal"What's covered" / plan selection modal
sb-cart-cta, sb-bottom-cart-ctaCart page and cart drawer calls-to-action
sb-line-item-badge, sb-warranty-details, sb-si-detailsCart line decorations
sb-checkout-widgetCheckout offering (platforms that render SDK UI in checkout)
sb-shipping-insurance, sb-shipping-insurance-popup, sb-shipping-insurance-cart-popupShipping protection
sb-post-purchase-modalPost-purchase / thank-you offering
sb-registration-pageProduct registration page

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.