The Script Tag Is a Trust Decision
Every analytics product starts with the same ask: paste this tag into your <head>. It reads like a copy-paste, but it's a trust decision. You're granting a vendor the right to run code on every page you serve — and to keep running whatever that code becomes after every silent update, forever.
Most vendors answer that trust question with a brand. We'd rather answer it with numbers you can check with curl. This post walks through the ClickStream install exactly as it ships: what the tag loads, what it weighs, where it's served from, what it sets, and what happens when things go wrong.
What You Paste: 344 Bytes
The entire integration contract is one script tag with one attribute:
<script
src="https://t.example.com/sdk.js"
data-key="cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
async
></script>Notice what isn't there: no site ID, no inline config blob, no snippet of bootstrap JavaScript to keep in sync across pages. data-key is the whole interface. And t.example.com isn't our domain — it's yours, a subdomain you CNAME to ClickStream during setup.
/sdk.js is not the SDK. It's an immutable loader that measures exactly 344 bytes — a number you can verify yourself with curl -sI against your tracking domain once it's live. Because the loader's content never changes, it ships with Cache-Control: public, max-age=31536000, immutable: browsers cache it for a year and never ask again.
What It Loads: ~56.5 KB, Honestly Weighed
The loader has exactly one job: inject a second script, /sdk/bundle.js, from the same first-party hostname. That's the real SDK — 208,684 bytes uncompressed, about 56.5 KB gzipped over the wire, loaded asynchronously. Both figures are measured, not estimated: the file in our repo and the file served in production are byte-identical.
We publish the real number because the industry habit — quote the loader, imply the bundle — erodes exactly the trust an analytics install depends on. Here's what ~56.5 KB compressed buys: pageview, click, form, and session capture; SPA route-change handling; first-party identity; capture of 13 ad-platform click-ID types from both the URL and the referrer; and the interaction telemetry that feeds behavioral scoring.
What the bundle deliberately doesn't include is a scoring engine. All 26 behavioral models run at the edge, inside the collector, at the moment each event is ingested — and a CI-enforced benchmark fails our build if the full scoring pass exceeds 3 ms at p95. Your visitors' browsers do the observing; our infrastructure does the thinking.
The performance cost on your side is correspondingly small: the tag loads async, events leave in roughly 2 KB batches every 5 seconds, and the documented Lighthouse impact on our reference site is typically 0–2 points.
Pin It Once: The Permanent SRI Hash
Subresource Integrity is the browser feature everyone praises and almost no analytics vendor supports. The reason is structural: SRI pins the hash of a file, and vendors change their file constantly. Change the file, break every customer's pin.
The two-stage design dissolves that conflict. Because the 344-byte loader is immutable, its hash is permanent. /sdk/integrity.json on your tracking domain publishes the loader's SHA-384 — pin it once and never touch your HTML again:
<script
src="https://t.example.com/sdk.js"
data-key="cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
integrity="sha384-[value from https://t.example.com/sdk/integrity.json]"
crossorigin="anonymous"
async
></script>SDK updates ship behind the loader: the bundle evolves, your pinned hash keeps verifying. If the loader ever failed its integrity check, the browser would refuse to execute it. That's the guarantee SRI was designed to give — and a mutable, monolithic tag structurally cannot offer it.
Your Subdomain, Not Ours
First-party isn't a mode you toggle on. It's the only mode we support — we don't sell direct access to our collector or SDK endpoints at all. Setup is one CNAME, t.yourdomain.com pointed at ClickStream (plus TXT validation records if Cloudflare asks for them during SSL provisioning). Once the hostname is verified, both the loader and the bundle serve from your own domain, and on a verified custom hostname the loader endpoint is keyless — the hostname itself is the proof.
One edge case worth naming because it bites people elsewhere: this works even when your domain is already on Cloudflare. CNAMEing across Cloudflare accounts normally triggers Error 1014. ClickStream routes custom hostnames through Cloudflare for SaaS, which exists for exactly this pattern — your zone stays yours, and tracking resolves anyway.
The 400-Day Cookie
Everything above exists to earn one capability: setting cookies the browser treats as genuinely first-party. Safari's Intelligent Tracking Prevention caps JavaScript-set cookies at 7 days — which quietly turns most analytics tools' "persistent" visitor IDs into week-long ones for a large share of traffic.
Because your tracking subdomain is a true first-party host, ClickStream's collector sets identity cookies server-side, via Set-Cookie response headers on your domain:
| Cookie | Max-Age | Role |
|---|---|---|
_cs_vid |
400 days | Visitor ID |
_cs_uid |
400 days | Cross-site clickstream ID |
_cs_sid |
1 day | Session ID |
All are Secure with SameSite=Lax. Server-set first-party cookies aren't subject to ITP's 7-day JavaScript cap, so identity persists for 400 days — the long-term maximum modern browsers allow (it's Chrome's hard cap on cookie lifetime; we don't claim "two years" because no browser grants two years). The practical difference: a customer who researched you in March and returns in month thirteen is still the same visitor — not a stranger by day eight.
Domain-Gated Keys: Public, But Useless Elsewhere
Your data-key value is public — it sits in your page source, as every browser analytics key must. It's also useless anywhere but your site. Website keys are domain-gated: the collector verifies each request's origin against the domains registered to your key, and events from an unregistered hostname are rejected with 403 domain_not_allowed. Scraping your key doesn't let anyone pollute your data from another domain.
The key families keep scopes honest, too: cs_live_* for browsers (domain-gated), cs_srv_live_* for servers, cs_mob_live_* for native mobile apps (provenance-exempt, because apps have no Origin header to check), and cs_test_* for testing. A server key never masquerades as a browser; a mobile app never has to fake a web URL.
Failure Is Engineered, Too
The sharpest test of a third-party tag isn't how it behaves when everything works — it's what it does to your site when something breaks on the vendor's side.
If a ClickStream account is suspended, the loader endpoint serves a silent one-line comment script: valid JavaScript that does nothing. No console errors, no failed network chains lighting up your customers' DevTools, no broken pages. Your site behaves as if the tag were never there.
The same philosophy applies to billing on paid tiers: passing your usage allowance never cuts off ingestion mid-month — paid plans fail open, and overage billing is opt-in. A billing limit is a conversation, not an outage.
What the Install Unlocks in Your Code
Once the pixel is live, the same first-party pipeline that fills your dashboard becomes readable from page code through Signals. The Signals packages are a developer preview today (0.1.0-alpha on npm; the core @clickstreamhq/sdk is stable at 1.4.0), and this is what the real API looks like:
import { configure, getVisitor, isBot, isHighIntent } from '@clickstreamhq/signals';
// configure() must run before any read — getVisitor() throws otherwise
configure({ apiKey: 'cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' });
const visitor = await getVisitor();
if (isBot(visitor)) {
// 158 named bots across 8 categories — including 38 named AI agents
console.log(visitor.bot.category, visitor.bot.name);
} else if (isHighIntent(visitor)) {
// helper convention: visitor.scores.intent >= 70
showDemoOffer();
}Reads round-trip in a documented 50–150 ms, and snapshot reads work on every tier — including the free one. The bot identity attached to visitor.bot comes from the same registry of 158 named bots that keeps automated traffic out of your human metrics in the first place.
Check Our Math
Nothing in this post asks you to take our word for it. Once your CNAME verifies — most installs finish in minutes once DNS propagates — every claim here is testable from your terminal:
- 344 bytes:
curl -sI https://t.yourdomain.com/sdk.jsand read thecontent-length. - Permanent SRI: fetch
/sdk/integrity.json, pin the SHA-384, and leave it pinned through every SDK release. - ~56.5 KB gzipped: watch
/sdk/bundle.jsin the DevTools Network tab, from your own hostname. - 400-day cookies: inspect
_cs_vidin the Application tab — server-set, on your domain. - Domain gating: replay an event from an unregistered origin and collect your
403 domain_not_allowed. - Seconds to first data: load a page and watch the session appear in the dashboard's Live Sessions panel.
A tracking pixel is the most widely deployed code a vendor ever ships. It should be the most carefully engineered — and the easiest to audit.
That's the standard the 344-byte loader is built to: small enough to read, immutable enough to pin, first-party enough to persist, and polite enough to disappear silently if it ever has nothing to say.