Web SDK - Datalyr Docs

Complete reference for @datalyr/web, which sends events to https://ingest.datalyr.com. For a first install, start with Install web tracking.

Install

Script tag
npm

<script
  defer
  src="https://track.datalyr.com/dl.js"
  data-workspace-id="YOUR_WORKSPACE_ID"
></script>

The script tag reads these attributes:

Attribute	Required	Effect
`data-workspace-id`	Yes	The workspace that receives events.
`data-endpoint`	No	Overrides the ingest URL. Defaults to the script origin when that origin is not `*.datalyr.com`.
`data-tracked-params`	No	More URL parameters to capture. Comma-separated.
`data-debug`	No	`true` turns on console logging.
`data-auto-identify`	No	`true` or `false`.
`data-platform`	No	`shopify`, `checkoutchamp`, or `generic`.
`data-checkout-champ-domains`	No	Comma-separated domains.
`data-stripe-payment-links`	No	`false` turns off Stripe link decoration.
`data-stripe-link-domains`	No	Comma-separated extra Stripe domains.

npm install @datalyr/web

import datalyr from '@datalyr/web'

datalyr.init({ workspaceId: 'YOUR_WORKSPACE_ID' })
await datalyr.ready() // resolves once the SDK accepts events

Never load the script tag and the npm package together. Two instances issue two visitor_id values for one person and split the journey.

init() throws when workspaceId is missing. Tracking methods called before init() warn and return.

What the SDK tracks without your code

Two triggers fire on their own:

Trigger	Event name	Turn it off with
First page view after load	`pageview`	`trackPageViews: false`
SPA route change (`pushState`, `replaceState`, `popstate`, `hashchange`)	`pageview`	`trackSPA: false`

Nothing else is automatic: no clicks, scrolls, form submits, outbound links, or errors. There is no session-start event, because session data rides on every event. Call track() for everything else.

Events the SDK sends for you

These names are reserved. Never send one yourself.

Method you call	Event name sent
`identify()`	`$identify`
`group()`	`$group`
`alias()`	`$alias`
`screen()`	`pageview`, with a `screen` property
`trackAppDownloadClick()`	`$app_download_click`
Auto-identify email capture	`$auto_identify`, then `$identify`

Identity

Four identifiers ship on every event. They are not alternatives to each other.

Wire field	Value
`visitor_id`	The anonymous browser ID, format `anon_<uuid>`. Stays anonymous even after `identify()`.
`user_id`	The ID you pass to `identify()`. `null` until then.
`distinct_id`	The `user_id` when identified. The `visitor_id` before that.
`session_id`	Format `sess_<uuid>`. New after 60 minutes idle.

Use visitor_id in server-side and webhook work. Stripe, Whop, and Shopify all key off it. Use distinct_id when you reason about event-level identity.

The Events and Conversions tables label this column distinct id. For an unidentified visitor it shows the visitor_id. Search there to trace a visitor.

// Pass your database user ID, not an email. Emails change, and a changed
// email creates a second user with a split journey.
datalyr.identify('user_123', {
  email: '[email protected]',
  plan: 'pro'
})

Call it after sign-in. Passing a different user_id runs reset() first, so two people on one browser do not merge.

Identity methods

Method	Returns
`getVisitorId(): string`	The anonymous browser ID. Same value as `getAnonymousId()`.
`getAnonymousId(): string`	The anonymous browser ID.
`getUserId(): string \| null`	The `user_id`, or `null`.
`getDistinctId(): string`	The `user_id` when identified, otherwise the `visitor_id`.
`getSessionId(): string`	The current session ID.
`getSessionData(): SessionData \| null`	The full session record.
`startNewSession(): string`	Ends the current session and returns a new session ID.

reset and alias

datalyr.reset() // logout only

Call reset() on logout. It clears user_id, traits, super properties, the captured email, the journey, and both touchpoints, then issues a new visitor_id and session. It leaves the Meta _fbc and _fbp cookies in place.

datalyr.alias('user_123')

alias(userId, previousId?) accepts only the current anonymous ID as previousId. Any other value logs a warning and does nothing.

Do not call reset() on every page load. A new visitor_id breaks the link between the campaign visit and the later conversion.

Track an event

datalyr.track('signup_clicked', {
  location: 'pricing_page'
})

Page views

datalyr.page({ title: 'Pricing', variant: 'A' })
datalyr.screen('Checkout', { step: 2 })

Use page() only with automatic tracking off, or for a second view on one URL.

Attribution

const attribution = datalyr.getAttribution()
const journey = datalyr.getJourney()

datalyr.setAttribution({
  utm_source: 'partner',
  utm_campaign: 'spring_launch'
})

First touch and last touch persist for the attributionWindow, 90 days by default.

Click IDs captured

The SDK reads these 15 parameters from the URL. Matching is case-sensitive.

Parameter	Platform	Parameter	Platform
`fbclid`	Meta	`dclid`	Google Display
`gclid`	Google Ads	`epik`	Pinterest
`gbraid`	Google Ads, iOS	`rdt_cid`	Reddit
`wbraid`	Google Ads, web	`obclid`	Outbrain
`ttclid`	TikTok	`irclid`	Impact
`msclkid`	Microsoft	`ko_click_id`	Klaviyo
`twclid`	X	`sclid`	Snapchat
`li_fat_id`	LinkedIn

These are normalized to a canonical name:

In the URL	Stored as
`ScCid`, `sccid`	`sclid`
`irclickid`	`irclid`

A URL carrying several click IDs sends all of them. clickIdType takes the first match in the order above. Any click ID forces medium to cpc.

Campaign parameters captured

Group	Parameters
UTM	`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`
Always captured	`lyr`, `ref`, `source`, `campaign`, `medium`, `gad_source`
Your `trackedParams`	Added to the rows above, never replacing them

Each UTM is sent twice: under its full name and under its stripped alias, so utm_source and source.

Ad platform cookies read

Platform	Cookies	Survives a marketing decline
Meta	`_fbp`, `_fbc`	No
Google Ads	`_gcl_aw`, `_gcl_dc`, `_gcl_gb`, `_gcl_ha`, `_gac`	No
Google Analytics	`_ga`, `_gid`	Yes
TikTok	`_ttp`, `_ttc`	No
Snapchat	`_scid`	No

Campaign parameters survive a marketing decline. The SDK writes _fbc and _fbp itself when a fbclid arrives and Meta has not set them. Both last 90 days.

datalyr.setConsent({ analytics: true, marketing: false })

setConsent() is safe to call before init(). The SDK stores the choice and applies it at initialization.

Method	Effect
`optOut()`	Stops all tracking. Writes the `__dl_opt_out` cookie. Stops Stripe link decoration.
`optIn()`	Resumes tracking.
`isOptedOut(): boolean`	Current opt-out state.

privacyMode: 'strict' forces autoIdentify off and stops email prefill on Stripe links. The SDK honors Global Privacy Control by default, and ignores Do Not Track unless respectDoNotTrack is true.

Checkout metadata

const stripe = datalyr.getStripeMetadata()
// { client_reference_id: 'anon_...', metadata: { visitor_id: 'anon_...' } }

const whop = datalyr.getWhopCheckoutMetadata()
// { visitor_id: 'anon_...' }

Pass getStripeMetadata() into the Stripe object your server creates. See Stripe for each surface. Whop metadata is optional. Use getWhopCheckoutMetadata() only when your code creates the Whop checkout configuration.

Automatic Stripe link decoration

With stripePaymentLinks on, the SDK stamps:

Surface	Receives
`<a>` links to `buy.stripe.com`, plus any host in `stripeLinkDomains`	`client_reference_id`, and `prefilled_email` when an email is known
`<stripe-pricing-table>`, `<stripe-buy-button>`	The `client-reference-id` attribute only, never an email

prefilled_email is skipped when prefilled_email or locked_prefilled_email is already present, or privacyMode is strict. The SDK re-stamps on click and watches the DOM for new links, debounced at 150 ms.

The SDK never decorates checkout.stripe.com URLs, because Stripe ignores these parameters on an already-created Checkout Session. It also cannot reach links opened with window.open(), links inside an iframe, or links in shadow DOM. Call getVisitorId() and pass the value yourself in those cases.

Super properties

Super properties attach to every later event. reset() clears them.

datalyr.setSuperProperties({ app_version: '2.4.0' })
datalyr.getSuperProperties()
datalyr.unsetSuperProperty('app_version')

Complete method list

Method	Signature
`init`	`(config: DatalyrConfig) => void`
`ready`	`() => Promise<void>`
`track`	`(eventName: string, properties?: EventProperties) => void`
`identify`	`(userId: string, traits?: UserTraits) => void`
`page`	`(properties?: PageProperties) => void`
`screen`	`(screenName: string, properties?: Record<string, any>) => void`
`group`	`(groupId: string, traits?: Record<string, any>) => void`
`alias`	`(userId: string, previousId?: string) => void`
`reset`	`() => void`
`flush`	`() => Promise<void>`
`destroy`	`() => void`
`getWorkspaceId`	`() => string \| null`
`getVisitorId`	`() => string`
`getAnonymousId`	`() => string`
`getUserId`	`() => string \| null`
`getDistinctId`	`() => string`
`getSessionId`	`() => string`
`getSessionData`	`() => SessionData \| null`
`startNewSession`	`() => string`
`getAttribution`	`() => Attribution`
`getJourney`	`() => TouchPoint[]`
`setAttribution`	`(attribution: Partial<Attribution>) => void`
`getStripeMetadata`	`() => { client_reference_id: string; metadata: { visitor_id: string } }`
`getWhopCheckoutMetadata`	`() => { visitor_id: string }`
`trackAppDownloadClick`	`(options: { targetPlatform: 'ios' \| 'android'; appStoreUrl: string }) => Promise<void>`
`setConsent`	`(consent: ConsentConfig) => void`
`optOut` / `optIn`	`() => void`
`isOptedOut`	`() => boolean`
`setSuperProperties`	`(properties: Record<string, any>) => void`
`unsetSuperProperty`	`(propertyName: string) => void`
`getSuperProperties`	`() => Record<string, any>`
`getErrors`	`() => ErrorInfo[]`
`getNetworkStatus`	`() => NetworkStatus`
`loadScript`	`(scriptId: string) => void`
`getLoadedScripts`	`() => string[]`

The default export and window.datalyr are one shared singleton. createDatalyrInstance() returns a second independent instance.

Configuration

Only workspaceId is required.

sessionTimeout and attributionWindow are milliseconds, not minutes or days. Setting sessionTimeout: 60 expires the session after 60 milliseconds.

Option	Type	Default
`workspaceId`	`string`	Required. Throws when missing.
`endpoint`	`string`	`'https://ingest.datalyr.com'`
`debug`	`boolean`	`false`
`batchSize`	`number`	`10`, clamped 1–1000
`flushInterval`	`number` ms	`5000`, clamped 250–3600000
`criticalEvents`	`string[]`	`['purchase','signup','subscribe','lead','conversion']`
`highPriorityEvents`	`string[]`	`['add_to_cart','begin_checkout','view_item','search']`
`sessionTimeout`	`number` ms	`3600000` (60 minutes)
`attributionWindow`	`number` ms	`7776000000` (90 days)
`trackedParams`	`string[]`	`[]`, merged onto the default list
`respectDoNotTrack`	`boolean`	`false`
`respectGlobalPrivacyControl`	`boolean`	`true`
`privacyMode`	`'standard' \| 'strict'`	`'standard'`
`cookieDomain`	`string \| 'auto'`	`'auto'`
`cookieExpires`	`number` days	`365`
`secureCookie`	`boolean \| 'auto'`	`'auto'`
`sameSite`	`'Strict' \| 'Lax' \| 'None'`	`'Lax'`
`cookiePrefix`	`string`	`'__dl_'`
`enablePerformanceTracking`	`boolean`	`true`
`enableFingerprinting`	`boolean`	`true`
`maxRetries`	`number`	`5`, clamped 0–20
`retryDelay`	`number` ms	`1000`, clamped 0–60000
`maxOfflineQueueSize`	`number`	`100`, clamped 1–100000
`trackSPA`	`boolean`	`true`
`trackPageViews`	`boolean`	`true`
`enableContainer`	`boolean`	`true`
`autoIdentify`	`boolean`	Off. Forced off when `privacyMode` is `'strict'`.
`autoIdentifyForms`	`boolean`	`true`
`autoIdentifyAPI`	`boolean`	`false`
`autoIdentifyShopify`	`boolean`	`true`
`autoIdentifyTrustedDomains`	`string[]`	`[]`
`shopifyCartAttributes`	`boolean`	`false`. Becomes `true` when `platform` is `'shopify'`.
`platform`	`'shopify' \| 'checkoutchamp' \| 'generic'`	Unset
`checkoutChampDomains`	`string[]`	Unset
`stripePaymentLinks`	`boolean`	`true`
`stripeLinkDomains`	`string[]`	`[]`
`fallbackEndpoints`	`string[]`	`[]`
`plugins`	`DatalyrPlugin[]`	`[]`

Datalyr can set autoIdentify, autoIdentifyForms, autoIdentifyAPI, autoIdentifyShopify, shopifyCartAttributes, checkoutChampDomains, respectGlobalPrivacyControl, respectDoNotTrack, and privacyMode remotely. A value you pass to init() always wins over the remote value.

Limits

Limit	Value
Events per batch	10, configurable to 1000
Flush interval	5000 ms
High-priority flush	1000 ms
Retries per batch	5
Offline queue	100 events. The oldest is dropped first.
`keepalive` request body	60000 bytes
`sendBeacon` chunk	60000 bytes
Duplicate suppression	The last 1000 event hashes
Journey length	30 touchpoints
Property nesting depth	5
Error buffer	50
Container script fetch	3000 ms timeout

There is no per-event size limit. Only the transport limits above apply.

How failed requests behave

Response	Behavior
`429`	Waits for `Retry-After`, default 60 seconds. The batch moves to the offline queue, and is not retried this cycle.
`403`	Sending pauses for 5 minutes, then resumes. An origin-allowlist rejection is configuration state, not a permanent error.
Other `4xx`, except `403` and `408`	Dropped permanently. Never retried. This is what a wrong `workspaceId` produces.
`5xx`, `408`, network failure	Retried with exponential backoff, up to `maxRetries`.

Storage

Cookie	Value	Lifetime
`__dl_visitor_id`	The `visitor_id`	365 days
`__dl_opt_out`	`true` or `false`	`cookieExpires`

__dl_visitor_id is written on the root domain with SameSite=Lax, and Secure on HTTPS. A failed root-domain write falls back to a host-only cookie. State lives in localStorage under a dl_dl_ prefix, for example dl_dl_anonymous_id and dl_dl_offline_queue. Traits and the captured email are encrypted with AES-GCM.

Lifecycle

await datalyr.flush()
datalyr.destroy()

flush() sends everything queued. destroy() removes listeners and stops the SDK. Use it only when you tear the integration down for good.

Verify the install

Open your published site in a private window.
Open Events in Datalyr.
Confirm a pageview arrives with your URL, within 30 seconds.

If nothing arrives, set debug: true, then call getErrors() and getNetworkStatus(). See No events.

​Install

​What the SDK tracks without your code

​Events the SDK sends for you

​Identity

​Identity methods

​reset and alias

​Track an event

​Page views

​Attribution

​Click IDs captured

​Campaign parameters captured

​Ad platform cookies read

​Consent and privacy

​Checkout metadata

​Automatic Stripe link decoration

​Super properties

​Complete method list

​Configuration

​Limits

​How failed requests behave

​Storage

​Lifecycle

​Verify the install

Install

What the SDK tracks without your code

Events the SDK sends for you

Identity

Identity methods

reset and alias

Track an event

Page views

Attribution

Click IDs captured

Campaign parameters captured

Ad platform cookies read

Consent and privacy

Checkout metadata

Automatic Stripe link decoration

Super properties

Complete method list

Configuration

Limits

How failed requests behave

Storage

Lifecycle

Verify the install