Frequently asked questions

Product

How does first-party tracking compare with third-party analytics?

ClickStream is first-party by default. Every event your visitor generates is sent to your own tracking domain (t.yourdomain.com), isolated by tenant-scoped keys in ClickStream's Cloudflare account, and surfaced in the dashboard. With third-party analytics, events flow through the vendor's domains and storage path. Concrete differences:

Blocking behavior. First-party CNAME tracking reduces common third-party blocking, but no analytics install is guaranteed against every blocker.
Cookie lifetime. Safari ITP clamps third-party cookies to 7 days. First-party cookies on your own domain persist at the browser's long-term maximum (~400 days). Visitors stay identifiable across return visits.
Data isolation. Tenant keys, retention controls, and exports are separated by site/account. ClickStream does not correlate visitors across customer tenants.
Real-time edge reads. The Signals API returns the current labeled snapshot from ClickStream's edge path. GA4's closest comparable export path is batch-oriented.

How does ClickStream compare with event-routing tools?

Event-routing tools send raw events to third-party destinations. ClickStream focuses on first-party collection plus edge-side classification:

Server-side scoring. ClickStream runs behavioral scoring models at the edge as events arrive. You read scores via the Signals API instead of building a separate warehouse pipeline first.
First-party delivery. Covered above.
Traffic classification. ClickStream labels every accepted event into human, crawler, answer-engine, monitor, automation, review, or suspicious lanes.
Optional enrichment on paid plans. When enabled, ClickStream can connect first-party signals to richer visitor profiles without making enrichment the core product.

Do I need a CMP / consent banner?

Depends on your jurisdiction. GDPR / UK GDPR / LGPD require explicit consent for marketing + identity categories (not necessarily analytics). CCPA / CPRA only require notice. HIPAA requires a BAA before go-live.

The SDK does not ship a consent banner. On compliance: 'gdpr_strict' (and hipaa) tracking defaults to denied until consent is granted. Consent comes from your own CMP — the SDK auto-detects OneTrust, Cookiebot, and Osano and mirrors their decision — or from an explicit window.cs.setConsent() call. Using a different CMP? Bridge its consent decision to the SDK with setConsent().

See Privacy & compliance for the full matrix.

Can I self-host?

Not today. ClickStream is tightly coupled to Cloudflare's edge (Workers, Durable Objects, Analytics Engine, KV, R2, Queues, D1) and rebuilding the platform on a different substrate is a large-scope engineering effort we do not currently support. Dedicated Cloudflare tenancy with EU-only or US-only residency is available by contract; contact support@clickstream.com.

Install & DNS

Why is first-party DNS mandatory?

The SDK only accepts events sent to a hostname your site has registered. Direct shared-endpoint installs are unsupported because domain validation, first-party cookie behavior, and CSP diagnostics depend on a registered tracking hostname.

See First-party tracking.

Can I host the SDK myself?

Technically yes — the SDK is an ES module you can serve from anywhere — but you'd lose automatic updates, cache-control headers tuned for our deploy cadence, and the collector's domain-validation handshake expects specific URL shapes. The standard supported install loads the SDK through the site's first-party CNAME. If you have a strong reason to self-host, contact support — it's a non-standard configuration.

What if my site is already behind Cloudflare?

Works fine. Add the tracking CNAME as DNS-only (gray cloud) even though the rest of your domain is proxied (orange cloud). Cloudflare for SaaS handles the cross-tenant routing.

Can I use Akamai / Fastly / AWS CloudFront as a CDN?

For your site: yes, no interaction with our platform. For the tracking subdomain: the CNAME must point at the ClickStream-issued Cloudflare for SaaS target. You don't proxy the tracking subdomain through your own CDN — we handle the edge.

Does the SDK slow my page down?

Script-tag install is async, so the SDK loads in parallel with the rest of your page and doesn't block render. First event fires after DOMContentLoaded. Total page-weight impact:

Script-tag install — browser pixel served from your first-party tracking domain with long-lived immutable caching.
NPM install helper — tiny DOM installer that injects the same browser pixel.
Ongoing event POSTs — ~2 KB per batch, every 5 seconds.

Lighthouse Performance scores on our reference test site typically move by 0–2 points with the SDK enabled vs disabled.

Data & privacy

What PII do you see?

Raw PII never touches our servers. The SDK hashes email (SHA-256 + MD5) and phone (E.164 → SHA-256) client-side before transmission. The collector only sees hashes.
Exception: opt-in raw capture. Sites can enable universal form-fill capture, which captures raw field values — those are AES-256-GCM encrypted on the collector before landing in D1, and only revealed via a password-gated, audit-logged /decrypt endpoint.
IP addresses are captured server-side from the request, encrypted at rest, and available only via the same reveal gate. The aggregate hashed IP (ipHash) feeds household grouping without exposing the raw value.

See Privacy & compliance.

Where is my data stored?

Cloudflare's global network by default. Enterprise contracts can lock to EU-only or US-only regions via signed DPA. Dashboard D1 and profile D1 are the two primary persistence stores; Analytics Engine handles the high-volume event stream; R2 holds Parquet exports.

How long do you retain data?

Event data (Analytics Engine) — the event stream has ~90-day platform retention; longer-horizon reporting comes from aggregates and exports.
Enriched person records — 90 days after last signal update, then auto-scrubbed.
Session replay — 1-hour peek on Hobby, 7 days on Growth, 30 days on Scale, 90 days on Network, contract-defined windows on Enterprise.
Encrypted raw values — per your site's compliance preset: 90 days on standard / ccpa / hipaa, 180 days on gdpr_strict. Auto-purge is on by default (retentionDays is configurable per site).
Audit log — 7 years (SOC2 window), append-only.

Visitor-initiated deletion removes the visitor from primary stores (dashboard D1, identity graph, enrichment cache) immediately, and tombstones suppress the visitor from all dashboard reads. Immutable Analytics Engine rows and previously exported Parquet files cannot be selectively erased — they age out within 90 days — and the visitor is excluded from all future exports.

Can I export all my data?

Yes.

CSV export — Growth+ tier, from the dashboard.
Parquet exports — provisioned on Scale+; exports currently run as an operator-assisted process from ClickStream's data lake. Delivery to a customer-owned S3 / R2 destination is not yet available.
Signals Feed WebSocket — Scale+ tier, real-time stream of every labeled event.
Per-visitor export — every site admin can export all data for a single visitor as a DSAR-style CSV + JSON bundle.

Will you train AI / ML on my data?

No. Your tenant's data is isolated under per-tenant HMAC + encryption keys. We don't run global models across tenants and don't share data with third-party ML vendors. Bot detection is heuristic-based classification combined with Cloudflare's bot-management signals — not a model trained on customer traffic.

Billing

How do overages work?

Monthly caps are included allowances, not a site-operation kill switch. If you exceed the included human pageview cap, the collector still accepts events and marks the response with over_limit_fail_open billing metadata so the dashboard can report the over-limit state.

Stripe overage billing is opt-in and only available once live billing is configured for the account. Until then, paid and active included-access accounts keep collecting without surprise charges. Sustained request-rate abuse can still receive 429s, but normal monthly usage over the included allowance does not stop page code from operating.

See Rate limits and Pricing.

What counts as a "pageview"?

Any billable event of type pageview — including SPA route changes (history.pushState / replaceState + hashchange navigations). An SPA route change is counted because the user is viewing a new page state, just delivered without a hard reload. Click, scroll, form, custom, and identify events do not count against the pageview cap.

The included-pageview cap on each tier is calibrated against real SPA + hard-reload traffic mixes, so you don't need to do anything special — just install the SDK, pick a tier that matches your volume, and the cap applies to the pageview count your dashboard reports.

Do bot events count against my pageview quota?

Clearly bot-classed SDK pageviews do not count against the normal human pageview cap. Accepted Edge capture bot hits count toward Signals Coverage because Edge capture is the opt-in coverage layer for crawlers, answer engines, previews, monitors, and automation. Click, scroll, form, custom, and identify events help classification but do not count as human pageviews. We label bot and AI traffic so you can separate it from human usage, prove coverage, and decide how your site should respond.

What happens on downgrade?

Downgrades take effect at the start of the next billing cycle. Your current-tier features stay live until then. After the cycle rolls over, exported features (replay, graph queries, Signals Feed) become unavailable but your data is preserved — you can re-upgrade any time to re-enable.

Can I get a refund for a partial month?

Upgrades prorate forward (you pay the difference for the current period). Downgrades + cancellations do NOT prorate backward (you keep the full current-period features; next period is the lower tier).

If you hit a billing bug or unexpected charge, email billing@clickstream.com.

Technical

What browsers do you support?

The SDK ingests events from every browser that can execute JavaScript. On modern runtimes (evergreen Chrome / Edge / Firefox / Safari / Opera, iOS Safari 13+) every feature is available. On older runtimes the SDK automatically falls back to a more conservative transport (sendBeacon → fetch → XMLHttpRequest) so events still reach the collector — we deliberately do NOT silently drop traffic from old browsers, because doing so would create a blind spot in traffic classification (a spoofed-ancient-UA session would never be observed by the collector).

Feature-level notes on older runtimes:

Older IE / older WebKit — core tracking (pageview, click, session, identify) works via XMLHttpRequest fallback. Some behavioral trackers (mouse dynamics, hover intent, clipboard) rely on APIs that don't exist on these runtimes and are skipped automatically. Events still reach the dashboard and feed traffic classification.
Safari ITP — handled via your first-party tracking domain; cookie lifetime is unaffected by ITP's third-party-cookie restrictions.
In-app WebViews — iOS WKWebView + Android WebView work identically to Safari / Chrome respectively. Facebook / Instagram / TikTok in-app browsers are included.

Does the SDK work in a Shadow DOM?

Yes. Click auto-capture traverses Shadow DOM via event.composedPath(). Form-field intelligence + hover intent similarly. Replay frames capture the shadow root's structure.

Does the SDK work on AMP?

Partial. AMP's custom analytics trigger works for sending events via amp-analytics configuration pointing at your first-party endpoint. The behavioral trackers (hover intent, mouse dynamics, form-field intelligence) don't — AMP doesn't let custom JS run them.

Can I use the SDK inside a native app WebView?

Yes — it runs in any standard browser context including iOS WKWebView + Android WebView. A fully native-app adapter without WebView is not currently shipped.

How do I test before production?

Create a separate test site or request a support-assisted cs_test_ key for non-production traffic. Point your test site at a dedicated first-party tracking subdomain (e.g. t-test.example.com) so test traffic does not pollute your production data, and set debug: true in your SDK config to log everything to the console while you're verifying the install.

Test-key traffic flows through the same scoring + bot-detection pipeline as production, so what you see in the dashboard is exactly what you'll see after going live.

Support

How do I reach support?

Email support@clickstream.com — all paid tiers get email support. Billing questions go to billing@clickstream.com. Enterprise contracts can include additional support arrangements, agreed during provisioning.

Where's the changelog?

Customer-visible release notes live in the dashboard under Changelog. Major releases (new plan tiers, SDK migrations, API-surface changes) are announced via email to the primary contact on your account.

Can I report a bug?

Yes. Non-sensitive bugs: email support@clickstream.com or open a ticket from the dashboard. Security issues: security@clickstream.com — security reports are acknowledged promptly.