@clickstreamhq/sdk

Public helper for installing the ClickStream browser pixel from a verified first-party tracking domain.

The package intentionally exposes only safe end-user install helpers. The event tracker itself is loaded by the pixel script at https://t.example.com/sdk.js.

Install

npm install @clickstreamhq/sdk

import { installClickstreamPixel } from '@clickstreamhq/sdk';

installClickstreamPixel({
  apiKey: 'cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  endpoint: 'https://t.example.com',
  replay: true,
});

Exports

import {
  installClickstreamPixel,
  uninstallClickstreamPixel,
  isClickstreamPixelInstalled,
  buildClickstreamPixelUrl,
} from '@clickstreamhq/sdk';

Runtime bridge

After the pixel loads, use:

window.clickstream?.trackEvent({ name: 'cta_clicked', category: 'interaction' });
await window.clickstream?.identify('[email protected]');

For reads that need the latest user action to be visible immediately, flush the event queue before querying downstream Signals data. trackEventNow() also flushes lightweight interaction summaries first, so automation and mouse-quality signals reach the collector with the action instead of waiting for the timer:

await window.clickstream?.trackEventNow({ name: 'cta_clicked', category: 'interaction' });

await window.clickstream?.identify('[email protected]');
await window.clickstream?.flush();

const sessionId = window.clickstream?.getSessionId();

For live visitor scores and bot/answer-engine lanes, install @clickstreamhq/signals.

Minimal core tracker (@clickstreamhq/sdk/core)

For mobile/advanced consumers who want to manage the tracker in code with a tiny (<15 KB gzipped) footprint, import the minimal IdentityTrackerCore from the ./core subpath:

import { IdentityTrackerCore } from '@clickstreamhq/sdk/core';

const tracker = new IdentityTrackerCore({
  apiKey: 'cs_live_xxx',
  endpoint: 'https://t.example.com',
});
tracker.init();
tracker.trackEvent({ name: 'signup_clicked' });

It ships first-party visitor/session ids, pageview + click auto-capture, custom events, and batched delivery — without identity resolution, replay, consent management, or the behavioral trackers. Upgrade to the full hosted SDK by switching the import.

Docs: https://docs.clickstream.com/sdk/core