Event Collector

The storefront analytics endpoint the SureBright SDK reports to (POST /events/api/event): payload fields, required values, event names, and when a custom storefront has to call it directly.

The SDK reports shopper interactions with the protection offer to SureBright's event collector. Those events feed the Sales analytics in the merchant portal: how many product views had an offer, how many shoppers looked at a plan, how many added to cart with and without protection, and attach-rate experiments.

If the SDK runs on your pages, it does this for you and you can stop reading. Call the collector yourself only when the SDK cannot see the interaction: a native app, a server-rendered checkout the script cannot run in, or a storefront where you render the offer with your own UI from SureBright quote data. Without these events, that traffic is invisible in Sales analytics.

Endpoint#

text
POST https://api-external.surebright.com/events/api/event
Content-Type: application/json
  • Authentication: none. The route is deliberately unauthenticated so browsers can post to it; CORS allows any origin. Do not send anything you would not put in a public page.

  • The body is always a batch: { "eventList": [ ... ] }. A single event still goes in a one-element array.

  • Events are buffered server-side and written asynchronously; the response tells you how many were accepted, not that they were stored.

Response#

json
{ "isError": false, "acceptedCount": 2, "rejectedCount": 0, "webhookEventsPushedCount": 0 }
StatusMeaning
200 with acceptedCount / rejectedCountRejected events failed validation (see below) and were dropped silently.
200 with {"isError": true, "message": "No events to push"}eventList was missing or empty.
503The server could not buffer the batch. Retry later with the same events.

Event fields#

Field names are short wire keys. The server maps them to full names; unknown keys are stored as-is under their wire name. Keys the server owns (_id, userAgent, receivedAt, timestamp, metadata, productDetailMap) are ignored if you send them.

stringrequired

Event type. One of the names under Event types.

stringrequired

Store id, as SureBright knows your store (for Shopify, the *.myshopify.com domain).

stringrequired

When the event happened, as a strict ISO 8601 timestamp with a Z or ±hh:mm offset, for example 2026-11-09T14:03:21.512Z. Anything else (including a missing offset, or an impossible date such as 2026-02-30) rejects the event.

string

Visit id: a UUID you generate once per browser session and reuse on every event in it. Strongly recommended; if omitted the server stores INVALID_VISIT and the event cannot be joined into a funnel.

string

Page source. One of PRODUCT_PAGE, CART_PAGE, COLLECTION_PAGE, CHECKOUT_PAGE, THANK_YOU_PAGE, OTHER_PAGE, QUICK_VIEW_POPUP, CART_POPUP, or, for events raised from a popup, the popup name (NUDGE_POPUP, ADD_WARRANTY_POPUP, LEARN_MORE_POPUP, ADD_TO_CART_POPUP, REGISTRATION_POST_PURCHASE). May be prefixed with the control that triggered it, separated by #, for example ATC_BUTTON#PRODUCT_PAGE; the server splits the prefix into eventSource. Sales analytics counts product-page funnel events by ps = PRODUCT_PAGE.

string

Platform: SHOPIFY, BIGCOMMERCE, WOOCOMMERCE, or CUSTOM.

string

Store country code, for example US or CA.

string

Province/state the quote was priced for, when applicable.

string

SureBright quote id the event relates to.

string

SureBright quote item id (the specific plan).

string

Platform cart id / token, when known.

string

SureBright cart analytics id, when the SDK has stamped the cart with one. Omit if you do not have it.

string

Theme id.

string

Session treatment id, only when the store runs a SureBright experiment.

string

Error message, for SB_ERROR events.

string

Error code, for SB_ERROR events.

object

Product and plan details for the event. An empty string for any value is stored as null (that is how "no plan" is expressed).

The server adds eventId (if you did not send one), receivedAt, and a parsed userAgent from the request header.

Events containing a wt (webhook topic) field are treated as webhook events, not shopper events, and are discarded. Do not use that key.

Event types#

These are the et values the storefront SDK emits. Use the same names so your traffic lands in the same reports.

etWhen
SB_FETCHED_POLICYQuotes were fetched for a product the shopper is viewing. Sales analytics counts this as a product view with an offer.
SB_VIEWED_POLICYThe offer became visible, or a plan popup opened (with ps set to the popup name).
SB_VIEWED_POLICY_IMPRESSIONA widget surface was rendered and seen.
SB_VIEWED_CARTThe cart page or cart drawer was viewed.
SB_CLICKED_POLICYThe shopper selected a plan.
SB_UNCLICKED_POLICYThe shopper deselected a plan.
SB_CLICKED_LEARN_MOREThe shopper opened "what's covered".
SB_CLICKED_PROTECT_MY_PURCHASEThe shopper confirmed protection in a popup.
SB_CLICKED_NO_THANKSThe shopper declined protection in a popup.
SB_CLICKED_CLOSE_POPUP_ICONThe shopper closed a popup without choosing.
SB_CLICKED_ADD_WARRANTY_BUTTONThe shopper used an "add protection" call-to-action (cart).
ADD_TO_CARTThe shopper added a product to the cart, with or without a plan. ps carries the triggering control (e.g. ATC_BUTTON#PRODUCT_PAGE) and pd.p_plpid says whether protection went with it. Sent immediately, not batched.
SB_CLICKED_ADD_TO_CARTProtection was added from the product-registration flow. Older SDK builds also sent it for product-page adds, and the legacy product-page funnel chart still counts it.
SB_CONFIRMED_ADD_TO_CARTThe cart confirmed the add (quantities verified after the write).
SB_VIEWED_EXPERIMENTThe shopper was exposed to an experiment treatment (stid).
SB_ERRORThe SDK hit an error (em, ec).

Which events the merchant portal reads: the design/experiment analytics count SB_FETCHED_POLICY, SB_VIEWED_POLICY_IMPRESSION, SB_CLICKED_POLICY, ADD_TO_CART and SB_VIEWED_CART per visit; the legacy product-page funnel chart counts SB_FETCHED_POLICY, SB_VIEWED_POLICY and SB_CLICKED_ADD_TO_CART with ps = PRODUCT_PAGE. The minimum set that makes a custom storefront visible is SB_FETCHED_POLICY, SB_VIEWED_POLICY_IMPRESSION, SB_CLICKED_POLICY and ADD_TO_CART, each with a shared vi.

Example#

A shopper on a product page adds a product together with a 2-year plan:

const visitId = sessionStorage.getItem("sb_visit") ?? crypto.randomUUID();
sessionStorage.setItem("sb_visit", visitId);

await fetch("https://api-external.surebright.com/events/api/event", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Accept": "application/json" },
  keepalive: true,
  body: JSON.stringify({
    eventList: [
      {
        et: "ADD_TO_CART",
        sid: "your-store.myshopify.com",
        vi: visitId,
        pf: "SHOPIFY",
        ct: "US",
        ps: "ATC_BUTTON#PRODUCT_PAGE",
        etime: new Date().toISOString(),
        sqid: "7b9a6c31-f6c5-4110-a1f4-c69dca10ab06",
        sqiid: "047cd751-8737-45cd-b113-227312a88d51",
        pd: {
          p_pid: "6673746231399",
          p_vid: "39876543210987",
          p_pp: "649.99",
          p_pq: 1,
          p_plpid: "7080029454439",
          p_plvid: "40937702359143",
          p_plq: 1,
          p_plp: "69.00",
          p_pt: "2Y",
          p_dc: "USD",
          isqa: true
        }
      }
    ]
  })
});

For an add-to-cart without protection, send the same ADD_TO_CART event with p_plpid, p_plvid, p_plp, sqid and sqiid as empty strings, p_plq: 0 and p_pt: "0Y". That is exactly what the SDK sends, and the empty p_plpid is what analytics uses to tell the two apart.

Behaviour to copy from the SDK#

  • Batch up to 10 events per request; send immediately on add-to-cart, otherwise when the batch fills or the page unloads (keepalive: true).

  • Keep events you could not send and retry them on the next page load.

  • On Shopify, send nothing until the shopper's analytics consent allows it (see Consent gating).

  • Do not send events from crawlers or your own test tooling; they count as shoppers.