---
title: JavaScript SDK reference
description: Every Dozenfold browser SDK option and method, what the SDK captures on its own, and what it never does to a live storefront.
updated: '2026-10-06'
slug: sdk-reference
---

# JavaScript SDK reference

The Dozenfold SDK is one script, `https://cdn.dozenfold.com/sdk/v1.js`, that defines
`window.Dozenfold`. On Shopify the theme app embed loads and starts it for you; you only call the
methods below for handled errors or extra milestones. On a custom site you call `init` yourself; see
[Install on a custom site](/docs/install-custom-site).

Every method is safe to call at any time. None throws, and calls made before collection starts or
without consent return `false` and send nothing.

## What it captures on its own

After `init`, without further code:

- uncaught errors, unhandled promise rejections, errors thrown in timers and event listeners, and
  `Error` objects passed to `console.error`, with `cause` chains and `AggregateError` members
- failed requests (fetch and XHR, including cart and GraphQL failures) and failed scripts, styles
  and images, plus CSP violations
- page views with their page type, and the session's landing page, channel and campaign
- LCP, INP and CLS per page view, and browser stalls (long tasks) where supported
- rage clicks, dead-click candidates, repeated submits and similar friction patterns
- on Shopify, funnel stages through the Web Pixel

It does not capture input values, request or response bodies, or a persistent shopper identity.

## init(options)

```js
await Dozenfold.init({
  siteId: 'site_…',
  token: 'omz_pub_v1_…',
  origin: window.location.origin,
  consent: 'granted',
  release: 'web@2026.10.06',
  currency: 'EUR',
  pageTypes: { pdp: ['/p', '/design'], plp: ['/c'] },
});
```

| Option | Type | Notes |
| --- | --- | --- |
| `token` | string | Required. Public ingest token. It permits sending events, never reading data. |
| `siteId` | string | Custom sites. Your site id from onboarding. Do not combine with `shopId`. |
| `shopId` | string | Shopify only; the app embed sets it. |
| `origin` | string | Custom sites: must equal `window.location.origin`, so a copied snippet cannot report for another site. |
| `consent` | `'granted'` \| `'cookieless'` \| `'denied'` \| `'unknown'` \| `'required'` | See [consent](#consent). Default `'required'`, which follows Shopify's Customer Privacy API. Custom sites pass a value. |
| `release` | string | Custom sites. Your build or deploy id (letters, digits and `._:@/+~-`, up to 128 characters). Matches source maps and release comparisons. |
| `currency` | string | Custom sites. ISO 4217 code used for `funnel` order values sent without `currency_code`. |
| `pageTypes` | object | Custom sites. Path prefixes per page type: `home`, `plp`, `pdp`, `search`, `cart`, `checkout`, `other`. See [page types](#page-types). |
| `endpoint` | string | Collector URL. Default `https://ingest.dozenfold.com`. |
| `configUrl` | string | Remote config URL. Default `https://cdn.dozenfold.com/config/<site>.json`. |
| `debug` | boolean | Logs why something was not collected to the console. |

`init` throws only for invalid site options (missing id, both ids, or an `origin` that does not
match the page) and an invalid `release`. Everything else fails quietly.

### Consent

| Value | Behaviour |
| --- | --- |
| `granted` | Full collection with a random session id in the browser. Replay can run. |
| `cookieless` | Nothing is stored in the browser. Events carry no id; the collector groups them per day. Replay and `identify` do not run. |
| `denied`, `unknown` | Nothing is collected. |
| `required` | Follow Shopify's Customer Privacy API (Shopify themes only). |

Change it later with `setConsent`.

### Page types

Page types drive the journey funnel, page groups and revenue impact strata. Shopify paths
(`/products`, `/collections`, `/cart`, `/search`, `/checkout`) are recognised without configuration.
A custom site maps its own prefixes:

```js
pageTypes: { pdp: ['/design'], plp: ['/shop', '/c'], checkout: ['/pay'] }
```

Prefixes match whole path segments: `/design` matches `/design/123`, not `/designer`. The longest
prefix wins, and up to 100 prefixes are used.

## Methods

| Method | Returns | Use |
| --- | --- | --- |
| `setConsent(value)` | void | Custom sites. Call from your consent banner: `'granted'`, `'cookieless'`, `'denied'` or `'unknown'`. Collection starts or stops at once. |
| `funnel(stage, props?)` | boolean | Custom sites. Report a journey stage. See below. |
| `track(name, props?)` | boolean | Report an allowlisted commerce milestone. See below. |
| `captureException(error, { severity? })` | boolean | Report a handled error from a `try/catch` or error boundary. `severity: 'warning'` for a problem that is not an outright failure. |
| `identify(userId)` | boolean | Custom sites, granted consent only. Ties later sessions to your own user id (letters, digits and `._:-`, up to 128 characters). A different id first starts a fresh visitor. |
| `reset()` | void | On logout: sends what is queued, then starts a fresh visitor and session. |
| `flush()` | void | Sends queued events now, for example before a client-side redirect. |
| `destroy()` | void | Removes every listener and wrapper the SDK installed. |
| `isInitialized()` | boolean | Whether `init` has finished. |

`true` means queued, not delivered.

### funnel

```js
Dozenfold.funnel('product_viewed', { product_id: 'sku-123' });
Dozenfold.funnel('product_added_to_cart', { product_id: 'sku-123' });
Dozenfold.funnel('checkout_started');
Dozenfold.funnel('checkout_completed', { order_value: 129.9, currency_code: 'EUR' });
```

Stages: `page_viewed`, `product_viewed`, `product_added_to_cart`, `checkout_started`,
`checkout_contact_info_submitted`, `checkout_address_info_submitted`,
`checkout_shipping_info_submitted`, `payment_info_submitted`, `checkout_completed`.
Properties are limited to `product_id` (string, up to 255 characters), `order_value` (non-negative
number) and `currency_code` (three uppercase letters). Send `order_value` on `checkout_completed` to
get revenue amounts; without it, impact reads in orders per day.

### track

```js
Dozenfold.track('wishlist_added', { quantity: 1, amount: 49.95, currency_code: 'USD' });
```

Names: `wishlist_added`, `wishlist_removed`, `product_compared`, `promotion_viewed`,
`promotion_clicked`, `search_submitted`. Properties: bounded `quantity`, paired `amount` +
`currency_code`, and boolean `success`. Up to 50 milestones per session. Free-text labels are
rejected.

## Error-session replay

Replay is not an SDK option. Turn it on in **Settings → Session replay**. The SDK then loads
`replay-v1.js` from the same CDN folder in sampled sessions with granted consent. See
[Error-session replay](/docs/replay).

## What the SDK never does to the store

The SDK is built so that a failure on our side never becomes a failure on yours:

- **Its own requests use the browser's native `fetch`**, not the page's. They do not pass through
  fetch wrappers installed by the theme or its apps, and those apps never see our traffic.
- **Keepalive budget.** Browsers share 64 KB of `keepalive` requests per page. Dozenfold uses at
  most 32 KB and 8 requests of it, shared with replay, so the store's own analytics and ad
  conversion beacons on page exit keep their room.
- **Wrappers are pass-through.** Request and listener wrappers return the original result and
  re-throw the original error; `window.open` always opens the popup, even if our bookkeeping fails.
- **No events dispatched to the page.** `setConsent` never fires Shopify's consent DOM event, so
  other scripts listening to it are not re-triggered.
- **Replay backs off.** A DOM mutation flood or a collector rate limit stops recording instead of
  slowing the page.
- **Bots are skipped.** In search-engine renderers, headless browsers and synthetic monitors
  (`navigator.webdriver`, Googlebot, Bingbot, Lighthouse and similar), `init` installs nothing.
- **Our frames stay out of your issues.** Stack frames from `cdn.dozenfold.com/sdk` are ignored
  when grouping errors.