The Web SDK tracks website activity, user identity, sessions, and attribution.
Install
import datalyr from '@datalyr/web'
datalyr.init({ workspaceId: 'YOUR_WORKSPACE_ID' })
await datalyr.ready()
<script
defer
src="https://track.datalyr.com/dl.js"
data-workspace-id="YOUR_WORKSPACE_ID"
></script>
Track an event
datalyr.track('signup_clicked', {
location: 'pricing_page'
})
Identify a user
Call identify after the user signs in or when you otherwise know their stable ID.
Track a page
datalyr.page({
title: 'Pricing',
variant: 'A'
})
page when you need to record one manually.
Core methods
| Method | Use it to |
|---|
init(config) | Initialize the SDK with a workspace ID. |
ready() | Wait for asynchronous initialization to finish. |
track(name, properties?) | Track an event. |
identify(userId, traits?) | Attach a stable ID and traits to the visitor. |
page(properties?) | Track a page view manually. |
alias(userId, previousId?) | Link two IDs that belong to the same person. |
reset() | Clear identity when a user signs out. |
flush() | Send queued events immediately. |
optOut() / optIn() | Change tracking preference. |
setConsent(consent) | Apply analytics and marketing consent. |
Privacy
datalyr.setConsent({
analytics: true,
marketing: false
})
reset() on logout so the next user does not inherit the previous user’s identity.
Configuration
Only workspaceId is required. These are the options most implementations need.
| Option | Type | Default | What it controls |
|---|
workspaceId | string | Required | The workspace that receives events. |
debug | boolean | false | Console logging during development. |
trackPageViews | boolean | true | Tracks the first page view. |
trackSPA | boolean | true | Tracks client-side navigation. |
trackSessions | boolean | true | Adds session data to events. |
sessionTimeout | number | 60 | Session timeout in minutes. |
attributionWindow | number | 90 | Attribution window in days. |
trackedParams | string[] | [] | Additional URL parameters to capture. |
privacyMode | 'standard' | 'strict' | 'standard' | Limits collection in strict mode. |
respectGlobalPrivacyControl | boolean | true | Respects the browser GPC signal. |
respectDoNotTrack | boolean | false | Respects the browser DNT signal when enabled. |
cookieDomain | string | 'auto' | 'auto' | Cookie domain used for identity. |
cookieExpires | number | 365 | Cookie lifetime in days. |
autoIdentify | boolean | false | Enables automatic email identification. |
enableContainer | boolean | true | Loads configured container scripts. |
platform | 'shopify' | 'checkoutchamp' | 'generic' | — | Enables platform-specific behavior. |
stripePaymentLinks | boolean | true | Adds Datalyr identity to supported Stripe payment links. |
Start with the defaults. Change batching, retry, cookie, or attribution options only when your implementation requires it.
Identity
Use a stable ID from your own system:
datalyr.identify(currentUser.id, {
email: currentUser.email,
plan: currentUser.plan
})
| Method | Returns |
|---|
getAnonymousId() | Persistent anonymous browser ID. |
getVisitorId() | Current visitor ID. |
getUserId() | Identified user ID, or null. |
getDistinctId() | User ID when identified; otherwise the anonymous ID. |
getSessionId() | Current session ID. |
alias(newId, previousId) only when both IDs belong to the same person. Use reset() for logout or account switching.
Attribution
const attribution = datalyr.getAttribution()
const journey = datalyr.getJourney()
datalyr.setAttribution({
utm_source: 'partner',
utm_campaign: 'spring_launch'
})
const stripe = datalyr.getStripeMetadata()
const whop = datalyr.getWhopCheckoutMetadata()
Super properties
Super properties are added to every later event:
datalyr.setSuperProperties({ app_version: '2.4.0' })
datalyr.unsetSuperProperty('app_version')
Lifecycle
await datalyr.flush()
datalyr.destroy()
flush() sends queued events. destroy() removes listeners and stops the SDK; only use it when the integration is being torn down permanently. 
