How do I install the ClickStream SDK?

Add a single script tag to your website's HTML head section with your site-specific API key. The SDK loads asynchronously, auto-captures page views, clicks, scroll events, and form interactions, and begins building visitor identity profiles immediately — no additional configuration required.

Does the ClickStream SDK slow down my website?

No. The SDK loads asynchronously and defers all processing to a Cloudflare Worker at the edge. The script itself is under 5KB gzipped, and all behavioral scoring happens server-side in under 3ms, adding zero impact to page load time or Core Web Vitals.

What events does the ClickStream SDK capture automatically?

The SDK auto-captures page views, click events, scroll depth, mouse movement patterns, form interactions, hover behavior, session timing, referrer data, UTM parameters, and ad platform click IDs (gclid, fbclid, msclkid, ttclid) — all without manual event instrumentation.

SDK Installation Guide | ClickStream Documentation

Your Dashboard Guides You Through This

When you log in to einstein.clickstream.com, the onboarding wizard walks you through SDK installation step by step. This guide covers the same steps in detail, plus advanced configuration.

Privacy Profile

Cookie consent & GDPR

DNS Setup

CNAME record

Add Snippet

You are here

Verify

Live data check

Done

Dashboard live

Method 1: Script Tag (Recommended)

The fastest way to get started. Add this snippet before the closing </head> tag on every page:

<script
  src="https://t.yourdomain.com/cs.js"
  data-site-id="YOUR_SITE_ID"
  data-key="cs_live_xxxxxxxxxxxxxxxxxxxxx"
  defer></script>

Replace t.yourdomain.com with your tracking subdomain (see the Tracking Domain Setup Guide) and YOUR_SITE_ID with the Site ID from your ClickStream dashboard.

What the Script Does

Sets a first-party cookie on your domain with 365-day persistence
Auto-captures page views, clicks, scroll depth, and form interactions
Captures UTM parameters and ad platform click IDs (gclid, fbclid, msclkid, ttclid)
Runs 26 behavioral scoring models at the edge in under 3ms
Builds a cross-device identity graph anchored to first-party cookies

Script Tag Attributes

Attribute	Required	Description
`src`	Yes	URL of the ClickStream SDK on your tracking domain
`data-site-id`	Yes	Your unique Site ID from the ClickStream dashboard
`data-key`	Yes	Your API key (starts with `cs_live_` or `cs_test_`)
`defer`	Recommended	Loads the script without blocking page render
`data-consent`	No	Set to `"required"` to block tracking until consent is granted
`data-auto-capture`	No	Set to `"false"` to disable automatic event capture

Method 2: NPM Package

For projects using a JavaScript build system:

npm install @clickstream/sdk

Then initialize in your application entry point:

import { ClickStream } from '@clickstream/sdk';

ClickStream.init({
  siteId: 'YOUR_SITE_ID',
  apiKey: 'cs_live_xxxxxxxxxxxxxxxxxxxxx',
  trackingDomain: 't.yourdomain.com',
});

NPM Configuration Options

Option	Type	Default	Description
`siteId`	string	—	Your unique Site ID (required)
`apiKey`	string	—	Your API key (required)
`trackingDomain`	string	—	Your CNAME tracking subdomain (required)
`autoCapture`	boolean	true	Automatically capture page views, clicks, scrolls
`consentRequired`	boolean	false	Block tracking until consent is granted
`cookieDomain`	string	auto	Override the cookie domain (e.g., `.yourdomain.com`)
`debug`	boolean	false	Enable console logging for debugging

SPA Route Change Tracking

Single-page applications need to track virtual page views when routes change. ClickStream handles this automatically for popular routers.

React Router

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
import { ClickStream } from '@clickstream/sdk';

function App() {
  const location = useLocation();

  useEffect(() => {
    ClickStream.page();
  }, [location]);

  return /* your routes */;
}

Next.js (App Router)

// app/providers.js
'use client';

import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';
import { ClickStream } from '@clickstream/sdk';

export function ClickStreamProvider({ children }) {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    ClickStream.page();
  }, [pathname, searchParams]);

  return children;
}

Vue Router

import { createRouter, createWebHistory } from 'vue-router';
import { ClickStream } from '@clickstream/sdk';

const router = createRouter({
  history: createWebHistory(),
  routes: [/* your routes */],
});

router.afterEach(() => {
  ClickStream.page();
});

export default router;

Identity Tracking

Connect anonymous visitors to known identities. Call identify when a user logs in, signs up, or provides their email:

ClickStream.identify('user-123', {
  email: 'user@example.com',
  name: 'Jane Doe',
  plan: 'enterprise',
});

CRM ID Mapping

Map visitors to your CRM records for full-funnel attribution:

ClickStream.identify('user-123', {
  email: 'user@example.com',
  salesforceId: '003xx000003abc',
  hubspotId: '12345',
  stripeCustomerId: 'cus_xxxxx',
});

The identity graph will merge all sessions for this visitor — including past anonymous sessions that were linked via the first-party cookie — into a single unified profile.

Custom Events

Track business-specific events beyond the auto-captured defaults:

ClickStream.track('purchase_completed', {
  orderId: 'ORD-9876',
  total: 149.99,
  currency: 'USD',
  items: 3,
});

ClickStream.track('feature_used', {
  feature: 'export_csv',
  plan: 'pro',
});

ClickStream.track('form_submitted', {
  formId: 'contact-us',
  source: 'pricing-page',
});

Event Naming Conventions

Use snake_case for event names (e.g., purchase_completed)
Use camelCase for property names (e.g., orderId)
Keep event names descriptive: noun_verb pattern (e.g., video_played, cart_updated)
Avoid high-cardinality event names (do not include IDs in the event name itself)

ClickStream integrates with your existing Consent Management Platform (CMP) or can operate in standalone consent mode.

Before Consent (Default Mode)

When consentRequired is set to true, the SDK loads but does not set cookies or send tracking data until consent is granted:

ClickStream.init({
  siteId: 'YOUR_SITE_ID',
  apiKey: 'cs_live_xxxxxxxxxxxxxxxxxxxxx',
  trackingDomain: 't.yourdomain.com',
  consentRequired: true,
});

Granting Consent

When the user accepts tracking (e.g., clicks "Accept All" on your cookie banner):

// User clicks "Accept" on your cookie banner
ClickStream.consent('granted');
// SDK begins tracking and sets first-party cookie

Revoking Consent

When a user revokes consent:

// User revokes consent
ClickStream.consent('revoked');
// SDK stops tracking, clears cookies, and deletes local data

CMP Integration Example (OneTrust)

// Listen for OneTrust consent changes
window.addEventListener('consent.onetrust', function(e) {
  if (e.detail.categories.includes('C0002')) {
    ClickStream.consent('granted');
  } else {
    ClickStream.consent('revoked');
  }
});

Cookieless Fallback

For the 15-22% of visitors who decline cookies, ClickStream falls back to a cookieless device recognition mode that still provides basic behavioral scoring (reduced from 26 to 4 models) without persistent identity. This data is session-scoped and not linked to the identity graph.

Verification

After installing the SDK, verify it is working correctly:

Check the Network tab — Open DevTools > Network. Filter for your tracking domain. You should see requests to /cs.js (SDK load) and /e (event payloads).
Check cookies — Open DevTools > Application > Cookies. Look for the _cs_id cookie on your domain with a 365-day expiration.
Check the dashboard — Log into the ClickStream dashboard. Navigate to Live View. You should see your visit appear within seconds.
Enable debug mode — Add data-debug="true" to the script tag (or debug: true in the NPM config). Open the browser console to see detailed SDK logging.

Performance Impact

ClickStream is designed to have minimal impact on page performance:

Metric	Impact
SDK file size	8.2 KB gzipped
Load strategy	Async/deferred — does not block page render
Event payload size	~1.2 KB per event
Edge processing latency	<3ms (Cloudflare Workers)
Main thread impact	<2ms per event
Lighthouse score impact	Negligible (0-1 point on Performance)

Full Configuration Reference

Option	Type	Default	Description
`siteId`	string	—	Your unique Site ID (required)
`apiKey`	string	—	Your API key (required)
`trackingDomain`	string	—	Your CNAME tracking subdomain (required)
`autoCapture`	boolean	true	Auto-capture page views, clicks, scroll depth, form interactions
`consentRequired`	boolean	false	Require consent before tracking
`cookieDomain`	string	auto	Override cookie domain for cross-subdomain tracking
`cookieExpiry`	number	365	Cookie expiration in days
`debug`	boolean	false	Enable console debug logging
`respectDoNotTrack`	boolean	false	Honor the browser DNT header
`sessionTimeout`	number	30	Session timeout in minutes of inactivity
`batchSize`	number	10	Number of events to batch before sending
`batchInterval`	number	5000	Max time (ms) before flushing event batch

Installing the SDK

Your Dashboard Guides You Through This

Method 1: Script Tag (Recommended)

What the Script Does

Script Tag Attributes

Method 2: NPM Package

NPM Configuration Options

SPA Route Change Tracking

React Router

Next.js (App Router)

Vue Router

Identity Tracking

CRM ID Mapping

Custom Events

Event Naming Conventions

Before Consent (Default Mode)

Granting Consent

Revoking Consent

CMP Integration Example (OneTrust)

Cookieless Fallback

Verification

Performance Impact

Full Configuration Reference

Go Live in Minutes. See ROI Immediately.

Installing the SDK

Your Dashboard Guides You Through This

Method 1: Script Tag (Recommended)

What the Script Does

Script Tag Attributes

Method 2: NPM Package

NPM Configuration Options

SPA Route Change Tracking

React Router

Next.js (App Router)

Vue Router

Identity Tracking

CRM ID Mapping

Custom Events

Event Naming Conventions

Consent Management

Before Consent (Default Mode)

Granting Consent

Revoking Consent

CMP Integration Example (OneTrust)

Cookieless Fallback

Verification

Performance Impact

Full Configuration Reference

Related Documentation

Tracking Domain DNS Setup

Migrating from GA4

Go Live in Minutes. See ROI Immediately.