Frequently asked questions

Product

How is ClickStream different from Google Analytics?

ClickStream is first-party by default. Every event your visitor generates is sent to your own domain (t.yourdomain.com), stored under per-tenant encryption keys in your Cloudflare tenancy, and surfaced to you through a dashboard you own. Google Analytics is third-party: events flow through Google's domains, land in Google's warehouse, and show up in a dashboard Google operates. Concrete differences:

Ad-blocker resilience. Most ad blockers pattern-match on google-analytics.com or googletagmanager.com and drop the events. Our first-party CNAME has no such pattern, so you recover 20–40% of events most operators lose.
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 ownership. You control the keys, the retention, and the export. We don't re-sell your data, don't train our bot-detection model on your users, and don't correlate visitors across tenants.
Real-time at the edge. The Signals API returns a labeled snapshot in ~50 ms. GA4's closest equivalent is BigQuery export with hours of delay.

How is ClickStream different from Segment / Mixpanel / Amplitude?

Those tools ship raw events to third-party analytics SaaS. ClickStream does the same job but:

Server-side scoring. We run 26 behavioral scoring models on-edge as events arrive. You read scores via the Signals API; you don't have to run your own warehouse + feature pipelines.
First-party delivery. Covered above.
Bot detection out of the box. Most analytics tools don't label bots; we classify every event into one of nine categories including a stealth-bot detector.
Identity graph included. Cross-device person records without a separate CDP vendor.

The tradeoff: Segment is a good choice when you need to fan events out to 100+ SaaS destinations. ClickStream is a good choice when you want first-party-owned analytics + identity + intelligence in one platform.

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.

Our SDK ships with a built-in banner configurable per site; set compliance: 'gdpr_strict' and showBannerOnLoad: true and the banner renders on first visit. You can also bring your own CMP — we auto-detect OneTrust / Cookiebot / Didomi / TrustArc / Osano / Sourcepoint via IAB TCF v2 and mirror the decision.

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 don't plan to do. Enterprise customers can get dedicated Cloudflare tenancy with EU-only or US-only residency; contact sales@clickstream.com.

Install & DNS

Why is first-party DNS mandatory?

Two reasons:

Quality. The SDK only accepts events sent to a hostname your tenant has registered. Direct-to-shared-endpoint installs drop the biggest value prop we sell — ad-blocker resilience, long-lived cookies, ASN reputation owned by you.
Sovereignty. Your visitors should see requests to your own domain, not a shared vendor domain. That's a brand-safety + legal-basis story we don't want to compromise for the convenience of skipping a CNAME.

The provisioning is 90 seconds of dashboard work. 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. In practice every customer loads the SDK through their first-party CNAME and lets us handle CDN + updates. 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 — 42 KB gzipped (one-time, 1-year immutable cache).
Core-only install — 2 KB gzipped.
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 Custom tier can lock to EU-only or US-only regions via signed DPA. Dashboard D1 and identity graph 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) — indefinite by default on paid tiers, configurable per plan.
Identity graph person records — 90 days after last signal update, then auto-scrubbed.
Session replay — 1-hour peek on Free, 7 days on Builder, 30 days on Scale, unlimited on Network+.
Encrypted raw values — per your site's retentionDays setting. Auto-purge is opt-in.
Audit log — 7 years (SOC2 window), append-only.

Visitor-initiated deletion scrubs everything except aggregate counts within 72 hours.

Can I export all my data?

Yes.

CSV export — Builder+ tier, from the dashboard.
Parquet exports — Scale+ tier, scheduled dumps to your own S3 / R2 bucket.
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, don't share data with third-party ML vendors, and don't train our own bot-detection model on identifiable customer traffic. The bot model is trained on synthetic + public-traffic corpora.

Billing

How do overages work?

By default, exceeding your monthly cap triggers rate-limiting (429s from the collector) until the next billing cycle. You can opt in to overage billing in the dashboard — then the collector keeps accepting events and meters them to Stripe at your tier's per-100k rate.

See Pricing — overage behavior.

What counts as a "pageview"?

Any event of type pageview — including SPA route changes (history.pushState / replaceState + hashchange navigations). An SPA route change is a genuine pageview: the user is viewing a new page, just delivered without a hard reload, and every analytics platform we've ever seen counts it the same way. Click, scroll, form, custom, and identify events do not count against the pageview cap; only pageview-type events do.

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?

Yes. Every event the collector accepts — human or bot — counts. We give you the label so you can filter them out of your reports, but the infrastructure cost of ingesting is the same regardless of verdict.

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 a pricing surprise that wasn't your fault, email billing@clickstream.com — those always get fixed.

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 bot detection (a spoofed-ancient-UA session would bypass ingestion entirely).

Feature-level notes on older runtimes:

Legacy 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 bot 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. For fully native-app integration (no WebView), a @clickstream/react-native adapter is on the roadmap but not shipped.

How do I test in staging?

Create a separate API key for your staging environment in the dashboard — keys prefixed cs_test_ are the convention for non-production use and are easy to spot in CI secret scanners and logs. Point your staging site at a dedicated first-party tracking subdomain (e.g. t-staging.example.com) so test traffic doesn't 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?

Free tier — community forum + GitHub discussions.
Builder — email support, 24-hour response SLA during business hours.
Scale — email + in-dashboard chat, 4-hour response during business hours.
Network — email + Slack Connect, 1-hour response 24/7.
Custom — dedicated Slack + named CS contact, quarterly business review.

Where's the status page?

status.clickstream.com — publishes alongside the public launch. We subscribe to Cloudflare's status feed for upstream incidents and correlate customer-visible impact.

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 — we triage 24/7 within 4 hours.