ClickStream Signals

Real-time visitor context for ClickStream-instrumented sites. Use Signals to adapt a page for people, AI crawlers, automation tools, kiosks, and high-intent visitors without breaking the default experience when the network is unavailable.

Install

npm install @clickstreamhq/sdk @clickstreamhq/signals

Basic Usage

import { installClickstreamPixel } from '@clickstreamhq/sdk';
import { configure, getVisitorOrNull, onVisitor, isBot } from '@clickstreamhq/signals';

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

configure({
  apiKey: 'cs_live_xxx',
  endpoint: 'https://t.example.com',
});

const visitor = await getVisitorOrNull();

if (visitor && isBot(visitor)) {
  document.documentElement.dataset.trafficLane = 'automation';
}

const subscription = onVisitor((context) => {
  document.documentElement.dataset.identityStatus = context.identity.status;
  document.documentElement.dataset.clickstreamId = context.identity.clickstreamId;
  document.documentElement.dataset.mergedIds = String(context.identity.mergedClickstreamIds.length);
});

// subscription.unsubscribe();

Identity IDs

identity.visitorId is the live browser visitor ID used by the Signals endpoint.

identity.clickstreamId is the stable ClickStream profile ID shown in the platform People view.

identity.observedClickstreamId is present when the current browser/session ID has already been merged into another profile.

identity.mergedClickstreamIds lists older ClickStream IDs that now resolve to identity.clickstreamId.

Fail Open

Use getVisitorOrNull() for site personalization. It returns null when Signals is unavailable, rate-limited, or blocked so your site keeps rendering its normal experience.