DEVELOPER API DEVELOPER PREVIEW

Your visitor data, in your code

Read live identity and behavioral signals and render your app by segment — in real time.

Signals is an NPM-first API that exposes the core intelligence powering the dashboard: identity status, a behavioral class, and live scores. Use it to personalize pages, gate content, and branch flows on first-party data you own.

What it is

The signals layer, defined

ClickStream Signals is a first-party data API that exposes each visitor's resolved identity, real-time behavioral class (human, suspicious, likely bot, or bot), and live behavioral scores to your own code — in the browser, in React, and on the server. It's the layer your site, app, or agent reads to decide what to show, who to trust, and what to do next.

First-party

Signals come from data you collect and own through your own tracking domain — no third-party cookies, no shared pixels.

Real-time

Scores update as the session unfolds, so decisions reflect what the visitor is doing right now. Snapshot reads work on every plan; realtime push streams are available on Scale and above — see plans.

Everywhere

One API across web, mobile, and server, so the same visitor is understood on every surface.

Core API

Read the visitor anywhere

One client for the browser and runtime (@clickstreamhq/signals), React hooks (@clickstreamhq/react), and a server resolver (@clickstreamhq/next). All three packages are in developer preview (alpha); @clickstreamhq/sdk is the stable package.

Browser / runtime

import { configure, getVisitor, onVisitor } from '@clickstreamhq/signals'; configure({ apiKey: 'cs_live_...' }); // Read the live visitor once const visitor = await getVisitor(); if (visitor.behavioralClass === 'human' && visitor.scores.intent >= 70) { showCheckoutOffer(); } // Or react to live updates onVisitor((v) => render(v));

React

import { useVisitor } from '@clickstreamhq/react'; function Offer() { const { ctx } = useVisitor(); if (ctx?.bot.isBot) return <Captcha />; return ctx && ctx.scores.intent >= 70 ? <BuyNow /> : <LearnMore />; }

Server (Next.js)

import { getServerVisitor } from '@clickstreamhq/next'; export default async function Page() { const { visitor } = await getServerVisitor({ apiKey: process.env.CLICKSTREAM_API_KEY!, // cs_srv_live_... }); return <Hero variant={visitor && visitor.scores.intent >= 70 ? 'high-intent' : 'default'} />; }
What each visitor exposes

Identity, behavioral class, and live scores

Identity status

Whether the visitor is anonymous or identified, plus the identifiers and cross-device IDs resolved through the identity waterfall.

Behavioral class

A real-time label — human, suspicious, likely_bot, or bot — to gate, challenge, or welcome.

Live scores

Intent, frustration, engagement, churn risk, and more from the 26-model scoring pipeline, updated as the session unfolds.

Effects engine

Define rules, let the UI adapt

Wire signals into a declarative rules engine: define conditions over scores and identity, and let effects fire — personalize content, gate flows, or suppress bots — without scattering conditionals through your codebase.

1

Read signals

Subscribe to the live visitor on the client or resolve it on the server.

2

Match rules

Conditions over behavioral class and scores decide which experience applies.

3

Apply effects

Render the right content, gate the risky sessions, branch the flow.

Read the full Signals API reference →

FAQ

Signals questions

ClickStream Signals is a first-party developer API that gives your application live access to each visitor's resolved identity, behavioral classification (human, suspicious, likely_bot, or bot), and real-time behavioral scores such as intent, frustration, engagement, and churn risk. You read it with @clickstreamhq/signals in the browser, @clickstreamhq/react hooks, or @clickstreamhq/next on the server.

Yes. Behavioral scores and the visitor's behavioral class update as the session unfolds, so the values you read reflect what the visitor is doing in the moment, not a stale snapshot.

Each visitor exposes identity status (anonymous or identified) and resolved identifiers, a behavioral class of human, suspicious, likely_bot, or bot, and live scores including intent, frustration, engagement, and churn risk from ClickStream's 26-model scoring pipeline.

The browser and runtime client is @clickstreamhq/signals, React bindings (useVisitor, useIdentify, useTrack) are in @clickstreamhq/react, and a server resolver (getServerVisitor) is in @clickstreamhq/next for Next.js middleware, route handlers, and server components.

Yes. Use getServerVisitor from @clickstreamhq/next to resolve a visitor's identity and scores server-side in Next.js middleware, route handlers, or server components for personalization before render.

A CDP routes events to destinations, and a feature-flag tool toggles static rules. ClickStream Signals gives your code the live, scored, identity-resolved state of the current visitor so you can personalize and gate based on real-time behavior — all on first-party data you own.

Read the visitor's behavioral class (human, suspicious, likely_bot, or bot) and bot fields. The classification combines request-level signals (Cloudflare Bot Management, a registry of 158 named bots, datacenter and header checks) with behavioral analysis such as mouse dynamics, cadence, and interaction patterns, so you can add CAPTCHA or gating only for risky sessions.

Yes. Signals are derived from data you collect and own through your own first-party tracking domain — there are no third-party cookies or shared pixels involved.

Build with Signals

Create a free account to get your keys and start reading signals from your code.

Start free