Skip to main content
The DATALYR Web SDK enables client-side event tracking, attribution capture, and identity resolution for websites and single-page applications.

​
What It Does

Browser Tracking:
  • Automatic pageview tracking
  • Custom event tracking
  • User identification and sessions
  • Attribution data capture (UTM params, referrers)
  • Device fingerprinting
  • Cross-domain tracking
  • Cookie management
  • Container/tag manager integration

​
Installation

Copy tracking script from Settings → Tracking Script: 
<script defer src="https://track.datalyr.com/dl.js"
  data-workspace-id="abc123xyz">
</script>
Place in <head> tag before closing </head> on all pages.

​
Option 2: npm Package

npm install @datalyr/web-sdk
Initialize: 
import datalyr from '@datalyr/web-sdk';

datalyr.init({
  workspaceId: 'abc123xyz'
});

​
Basic Usage

​
Track Events

// Track custom event
datalyr.track('button_click', {
  button_name: 'signup',
  page: 'homepage'
});

// Track with revenue
datalyr.track('purchase', {
  revenue: 99.99,
  currency: 'USD',
  product_id: 'prod_123'
});

​
Track Pageviews

Automatic (Default): Initial pageview tracked automatically on script load. Manual: 
// Track pageview manually
datalyr.page();

// With custom properties
datalyr.page({
  category: 'blog',
  author: 'John Doe'
});
SPAs (Single-Page Apps): Automatic tracking for React Router, Vue Router, Next.js navigation via history API monitoring.

​
Identify Users

// After user logs in
datalyr.identify('user_123', {
  email: '[email protected]',
  name: 'John Doe',
  plan: 'pro'
});
Links anonymous visitor to known user for attribution.

​
Reset on Logout

// Clear user identity
datalyr.reset();
Creates new anonymous visitor ID.

​
Configuration

​
Initialization Options

datalyr.init({
  workspaceId: 'abc123xyz',

  // Optional settings
  debug: false,                    // Enable debug logs
  endpoint: 'https://ingest.datalyr.com',

  // Queue settings
  batchSize: 10,                   // Events per batch
  flushInterval: 5000,             // Flush every 5s
  flushAt: 10,                     // Auto-flush at 10 events

  // Session settings
  sessionTimeout: 1800000,         // 30 min timeout
  trackSessions: true,

  // Attribution settings
  attributionWindow: 2592000000,   // 30 days
  trackedParams: ['utm_source', 'utm_medium', 'utm_campaign', 'gclid', 'fbclid'],

  // Privacy settings
  respectDoNotTrack: false,
  respectGlobalPrivacyControl: true,
  privacyMode: 'standard',         // 'standard' or 'strict'

  // Cookie settings
  cookieDomain: 'auto',            // Auto-detect or '.example.com'
  cookieExpires: 365,              // Days
  secureCookie: 'auto',
  sameSite: 'Lax',

  // Tracking settings
  trackPageViews: true,            // Auto-track pageviews
  trackSPA: true,                  // Track SPA navigation
  enableFingerprinting: true,
  enablePerformanceTracking: true,

  // Container settings
  enableContainer: true            // Load container scripts
});

​
Advanced Features

​
Super Properties

Properties sent with every event: 
// Set once, sent with all events
datalyr.setSuperProperties({
  app_version: '2.1.0',
  environment: 'production'
});

// Unset super property
datalyr.unsetSuperProperty('environment');

​
Manual Attribution

// Set attribution manually
datalyr.setAttribution({
  utm_source: 'google',
  utm_medium: 'cpc',
  utm_campaign: 'summer_sale'
});

// Get current attribution
const attribution = datalyr.getAttribution();

​
Journey Tracking

// Get customer journey (all touchpoints)
const journey = datalyr.getJourney();
// Returns array of attribution touchpoints

​
Session Management

// Get current session ID
const sessionId = datalyr.getSessionId();

// Get session data
const session = datalyr.getSessionData();

// Start new session manually
datalyr.startNewSession();

​
Identity Management

// Get anonymous ID
const anonId = datalyr.getAnonymousId();

// Get user ID (if identified)
const userId = datalyr.getUserId();

// Get distinct ID (userId or anonId)
const distinctId = datalyr.getDistinctId();

// Alias user (connect IDs)
datalyr.alias('user_123', 'previous_id');

​
Group Tracking

// Associate user with account/organization
datalyr.group('company_456', {
  name: 'Acme Corp',
  plan: 'enterprise'
});

​
Screen Tracking (SPAs)

// Track screen view
datalyr.screen('Dashboard', {
  section: 'analytics'
});

​
Opt-Out/Consent

// Opt user out of tracking
datalyr.optOut();

// Opt user back in
datalyr.optIn();

// Check opt-out status
const isOptedOut = datalyr.isOptedOut();

// Set consent preferences
datalyr.setConsent({
  analytics: true,
  advertising: false
});

​
Manual Flush

// Flush events immediately
await datalyr.flush();

​
Container Scripts

// Load custom container script by ID
datalyr.loadScript('script_abc123');

// Get loaded scripts
const loadedScripts = datalyr.getLoadedScripts();

​
Privacy Features

Cookies Created:
  • __dl_visitor_id: Visitor identifier (365 days)
  • __dl_session_id: Session identifier (30 min)
  • __dl_attribution: Attribution data (30 days)
  • __dl_opt_out: Opt-out status (permanent)
Cookie Domain: 
datalyr.init({
  cookieDomain: '.example.com'  // Share across subdomains
});

​
Do Not Track

datalyr.init({
  respectDoNotTrack: true  // Respect browser DNT setting
});

​
Global Privacy Control

datalyr.init({
  respectGlobalPrivacyControl: true  // Respect GPC signal
});

​
Fingerprinting

datalyr.init({
  enableFingerprinting: false  // Disable device fingerprinting
});

​
Performance Tracking

Automatic Performance Metrics:
  • Page load time
  • DOM ready time
  • First byte time
  • DNS, TCP, request times
Disable: 
datalyr.init({
  enablePerformanceTracking: false
});

​
Cross-Domain Tracking

Same Root Domain (Subdomains): Enable in Settings → Advanced → Cross-Domain Tracking → Include Subdomains. Cookies set on .example.com work across www.example.com, app.example.com, blog.example.com. Different Domains: Enable in Settings → Advanced → Cross-Domain Tracking and add domains to whitelist. Links automatically include _dl_visitor parameter to maintain identity.

​
Debugging

Enable Debug Mode: 
datalyr.init({
  debug: true
});
Check Status: 
// View SDK errors
const errors = datalyr.getErrors();

// View network status
const status = datalyr.getNetworkStatus();
Browser Console: All events logged to console when debug: true.

​
TypeScript Support

Full TypeScript definitions included: 
import datalyr, {
  DatalyrConfig,
  EventProperties,
  UserTraits
} from '@datalyr/web-sdk';

const config: DatalyrConfig = {
  workspaceId: 'abc123xyz',
  debug: true
};

datalyr.init(config);

const properties: EventProperties = {
  revenue: 99.99,
  currency: 'USD'
};

datalyr.track('purchase', properties);

​
Framework Integration

​
React

import { useEffect } from 'react';
import datalyr from '@datalyr/web-sdk';

function App() {
  useEffect(() => {
    datalyr.init({ workspaceId: 'abc123xyz' });
  }, []);

  const handleClick = () => {
    datalyr.track('button_click');
  };

  return <button onClick={handleClick}>Click Me</button>;
}

​
Vue

import datalyr from '@datalyr/web-sdk';

export default {
  mounted() {
    datalyr.init({ workspaceId: 'abc123xyz' });
  },
  methods: {
    handleClick() {
      datalyr.track('button_click');
    }
  }
}

​
Next.js

// pages/_app.js
import { useEffect } from 'react';
import datalyr from '@datalyr/web-sdk';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    datalyr.init({
      workspaceId: 'abc123xyz',
      trackSPA: true
    });
  }, []);

  return <Component {...pageProps} />;
}

​
Common Use Cases

E-commerce Tracking: 
// Product view
datalyr.track('product_view', {
  product_id: 'prod_123',
  name: 'Premium Widget',
  price: 99.99
});

// Add to cart
datalyr.track('add_to_cart', {
  product_id: 'prod_123',
  quantity: 2
});

// Purchase
datalyr.track('purchase', {
  order_id: 'order_456',
  revenue: 199.98,
  currency: 'USD',
  products: ['prod_123']
});
SaaS Tracking: 
// Signup
datalyr.track('signup', {
  plan: 'pro',
  trial: true
});
datalyr.identify('user_123', {
  email: '[email protected]'
});

// Feature usage
datalyr.track('feature_used', {
  feature: 'export_csv',
  count: 1
});

// Upgrade
datalyr.track('plan_upgrade', {
  from: 'pro',
  to: 'enterprise'
});
Lead Generation: 
// Form view
datalyr.track('form_view', {
  form_id: 'contact_form'
});

// Form submission
datalyr.track('form_submit', {
  form_id: 'contact_form',
  email: '[email protected]'
});
datalyr.identify('lead_123', {
  email: '[email protected]',
  source: 'contact_form'
});

​
Troubleshooting

Events Not Appearing:
  • Check workspace ID matches Settings
  • Open browser console and check for errors
  • Enable debug: true to see event logs
  • Check Event Stream for recent events
  • Verify script loads (Network tab)
Attribution Not Captured:
  • Check URL has UTM parameters
  • Ensure trackSessions: true
  • Verify cookies not blocked
  • Check trackedParams includes your params
Cross-Domain Not Working:
  • Enable in Settings → Advanced
  • Add all domains to whitelist
  • Check links include _dl_visitor param
  • Verify cookie domain settings

​
Browser Support

Supported:
  • Chrome 60+
  • Firefox 55+
  • Safari 12+
  • Edge 79+
  • Mobile browsers (iOS Safari, Chrome Mobile)
Graceful Degradation: SDK fails silently in unsupported browsers without breaking site functionality.

​
Next Steps

Server SDK

Backend tracking guide

Mobile SDKs

iOS & React Native guide

Advanced Topics

Identity, batching, plugins

Event Stream

Verify tracked events