@clickstreamhq/sdk

@clickstreamhq/sdk is the public browser pixel helper package. It does one job: install the ClickStream browser pixel from your verified first-party tracking domain.

The package does not expose ClickStream's internal tracker classes. The browser tracker itself is served by your tracking hostname at https://t.example.com/sdk.js, then it sends events to https://t.example.com/v1/events and exposes the small runtime bridge on window.clickstream.

Use this package when a framework or build system makes a static <script> tag inconvenient.

Install

pnpm add @clickstreamhq/sdk

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

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

The helper appends this script for you:

<script
  id="clickstream-sdk"
  src="https://t.example.com/sdk.js?key=cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  data-key="cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  data-endpoint="https://t.example.com"
  data-replay="true"
  async
></script>

Replace t.example.com with the tracking domain shown as active in Einstein. The collector rejects events when the request origin is not registered for the API key.

Public API

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

installClickstreamPixel(options)

Adds the pixel script to document.head and returns the installed script element.

const installed = installClickstreamPixel({
  apiKey: 'cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  endpoint: 'https://t.example.com',
  replay: true,
  followMe: true,
  campaignParams: ['ref', 'promo'],
  formBridgeOrigins: ['https://forms.example.com'],
  compliance: 'standard',
});

console.log(installed.alreadyInstalled);
console.log(installed.src);

Options:

uninstallClickstreamPixel(id?)

Removes the script tag by id. This is mainly useful in tests, previews, and single-page demos that mount/unmount complete app shells.

uninstallClickstreamPixel();

isClickstreamPixelInstalled(id?)

Checks whether the script tag exists.

if (!isClickstreamPixelInstalled()) {
  installClickstreamPixel({ apiKey, endpoint });
}

buildClickstreamPixelUrl(options)

Builds the loader URL without touching the DOM. Use it when you need to render a script tag yourself.

const src = buildClickstreamPixelUrl({
  apiKey: 'cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  endpoint: 'https://t.example.com',
});

Runtime bridge

After the pixel loads, it exposes:

window.clickstream?.trackEvent({ name: 'help_panel_opened', category: 'interaction' });
await window.clickstream?.identify('user@example.com');
await window.clickstream?.identifyPhone('+14155551234');
await window.clickstream?.captureFormSubmission('lead-form', {
  email: 'user@example.com',
  company: 'Example Inc',
});
const visitorId = window.clickstream?.getVisitorId();
const clickstreamId = window.clickstream?.getClickstreamId();

Use @clickstreamhq/signals to read scored visitor context. Use the runtime bridge to send events.

React example

'use client';

import { useEffect } from 'react';
import { installClickstreamPixel } from '@clickstreamhq/sdk';
import { ClickStreamProvider } from '@clickstreamhq/react';

export function Providers({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    installClickstreamPixel({
      apiKey: process.env.NEXT_PUBLIC_CLICKSTREAM_KEY!,
      endpoint: 'https://t.example.com',
      replay: true,
    });
  }, []);

  return (
    <ClickStreamProvider
      apiKey={process.env.NEXT_PUBLIC_CLICKSTREAM_KEY!}
      endpoint="https://t.example.com"
    >
      {children}
    </ClickStreamProvider>
  );
}

The installer creates the visitor/session cookies and starts event capture. The provider configures Signals reads for React hooks.

Minimal tracker — @clickstreamhq/sdk/core

The package also ships a tiny self-contained tracker on the ./core subpath for sites that want a small bundle without loading the full pixel from the tracking domain. It is a published export (@clickstreamhq/sdk/core), under 15 KB gzipped, and trades away identity resolution, replay, consent management, and the behavioral interaction trackers for size.

pnpm add @clickstreamhq/sdk

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

const tracker = new IdentityTrackerCore({
  apiKey: 'cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  endpoint: 'https://t.example.com',
});

tracker.init();
tracker.trackEvent({ name: 'signup_clicked' });

trackEvent / trackPageview are drop-in compatible with the full tracker, so upgrading to the full feature set is a one-line import change to @clickstreamhq/sdk. The IdentityTrackerCore class and its CoreConfig / CoreEvent types are the only exports of the ./core subpath.

Most browser apps should use installClickstreamPixel() (above), which loads the full tracker from your first-party domain. Reach for @clickstreamhq/sdk/core only when bundle size matters more than identity, replay, and behavioral scoring.

What this does not do

• The pixel helper does not run in Node.js or native mobile screens. It needs document.
• The pixel helper does not expose an importable IdentityTracker class. For a bundled tracker, use the @clickstreamhq/sdk/core subpath above; for native apps use @clickstreamhq/react-native.
• Neither surface replaces Edge capture for crawlers and answer engines that do not execute JavaScript.
• Neither replaces direct native app ingestion. See Mobile apps.

See also

• Install — full install matrix.
• Signals API — read live visitor context from page code.
• React adapter — hooks over the Signals client and runtime bridge.
• Mobile apps — native screen/event ingestion.