Migration at a Glance
ClickStream runs alongside GA4 first, so you never lose data. The full migration takes 5–6 weeks with zero downtime.
Week 1–2
Parallel Tracking
Run both tools side-by-side
Week 2–3
Event Mapping
Map GA4 events to ClickStream
Week 3–4
Dashboard Setup
Rebuild reports in Einstein
Week 5
Export & Remove
Export GA4 data, remove script
Why Migrate from GA4?
Google Analytics 4 served well as a free analytics tool, but it has fundamental limitations that become critical as businesses grow:
- Data sampling — GA4 samples data at scale, meaning your reports are based on estimates, not actual visitor behavior. ClickStream processes every event with zero sampling.
- Third-party data ownership — Your data lives on Google's infrastructure. Google uses it for ad targeting and can change access terms at will. ClickStream stores data on managed R2 infrastructure with AES-256-GCM encryption and full Parquet export capability.
- Limited identity resolution — GA4's User-ID feature requires explicit login. ClickStream builds identity graphs from first-party cookies, hashed emails, device signatures, and IP clustering — resolving anonymous visitors across devices.
- No behavioral intelligence — GA4 reports what happened. ClickStream's 26 real-time scoring models tell you what will happen — intent, churn risk, purchase timing, frustration.
- Cookie limitations — GA4 uses third-party cookies that are blocked by Safari ITP and Firefox ETP. First-party cookies on your domain achieve significantly higher recognition rates.
- Processing delays — GA4 has 24-48 hour data processing delays. ClickStream delivers real-time data with edge processing in under 3ms.
Migration Timeline Overview
| Phase | Timeline | Description |
|---|---|---|
| Phase 1 | Week 1-2 | Parallel tracking — run ClickStream alongside GA4 |
| Phase 2 | Week 2-3 | Event mapping — map GA4 events to ClickStream equivalents |
| Phase 3 | Week 3-4 | Dashboard migration — rebuild reports in ClickStream |
| Phase 4 | Week 5-6 | Remove GA4 — clean up tags and verify ClickStream is sole source |
Phase 1: Parallel Tracking (Week 1-2)
Week 1-2Install ClickStream alongside GA4 so both systems collect data simultaneously. This validates ClickStream is working before you remove GA4.
Step 1: Set Up Your Tracking Domain
Follow the Tracking Domain DNS Setup Guide to configure a CNAME subdomain (e.g., t.yourdomain.com).
Step 2: Install the 
SDK
Add the ClickStream SDK below your existing GA4 tag:
<!-- Existing GA4 tag (keep this for now) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');
</script>
<!-- Add ClickStream below -->
<script
src="https://t.yourdomain.com/cs.js"
data-site-id="YOUR_SITE_ID"
data-key="cs_live_xxxxxxxxxxxxxxxxxxxxx"
defer></script>
Step 3: Validate Parallel Collection
After installing both tags, verify data is flowing to both systems:
- Check the ClickStream Live View for real-time events
- Compare page view counts between GA4 and ClickStream after 24 hours
- Verify that ClickStream is capturing more visitors (first-party cookies will find users GA4 misses)
Expected result: ClickStream will typically show 15-40% more unique visitors than GA4 during parallel tracking because first-party cookies are not blocked by Safari ITP or Firefox ETP.
Phase 2: Event Mapping (Week 2-3)
Week 2-3Map your GA4 custom events to ClickStream equivalents. ClickStream auto-captures most standard events, so you only need to map custom ones.
Auto-Captured Events (No Mapping Needed)
ClickStream automatically captures these events without any code changes:
| GA4 Event | ClickStream Equivalent | Notes |
|---|---|---|
page_view |
Auto-captured | Includes full URL, referrer, UTMs |
scroll |
Auto-captured | Captures scroll depth at 25%, 50%, 75%, 100% |
click |
Auto-captured | Captures all clicks with element selector |
first_visit |
Auto-captured | First-party cookie creation event |
session_start |
Auto-captured | 30-minute inactivity timeout (configurable) |
user_engagement |
Auto-captured | Plus 26 behavioral scoring models |
form_start |
Auto-captured | Detects form focus events |
form_submit |
Auto-captured | Captures form submissions with field names |
file_download |
Auto-captured | Tracks PDF, XLSX, DOCX, CSV downloads |
video_start |
Auto-captured | YouTube and HTML5 video support |
Custom Event Mapping
Replace gtag('event', ...) calls with ClickStream.track():
| GA4 Code | ClickStream Code |
|---|---|
gtag('event', 'purchase', {value: 99}) |
ClickStream.track('purchase_completed', {value: 99}) |
gtag('event', 'sign_up', {method: 'email'}) |
ClickStream.track('sign_up', {method: 'email'}) |
gtag('event', 'add_to_cart', {items: [...]}) |
ClickStream.track('cart_updated', {items: [...]}) |
gtag('event', 'generate_lead') |
ClickStream.track('lead_generated', {}) |
E-Commerce Event Mapping
| GA4 E-Commerce Event | ClickStream Equivalent |
|---|---|
view_item |
product_viewed |
add_to_cart |
cart_updated (action: 'add') |
remove_from_cart |
cart_updated (action: 'remove') |
begin_checkout |
checkout_started |
add_payment_info |
payment_info_added |
purchase |
purchase_completed |
refund |
refund_processed |
Identity Mapping
Replace GA4's user_id with ClickStream's identify:
// GA4 (before)
gtag('config', 'G-XXXXXXXXXX', {
user_id: 'USER_ID'
});
// ClickStream (after)
ClickStream.identify('USER_ID', {
email: user.email,
name: user.name,
});
Phase 3: Dashboard Migration (Week 3-4)
Week 3-4Rebuild your GA4 reports in the ClickStream dashboard. Many reports will be automatically available; others need custom configuration.
Standard Reports (Available Immediately)
- Real-time Overview — Live visitor count, active pages, geographic distribution
- Acquisition — Traffic sources, UTM breakdown, click ID attribution (gclid, fbclid, msclkid, ttclid)
- Engagement — Page views, session duration, scroll depth, bounce rate
- Identity — Visitor recognition rate, cross-device connections, identity graph coverage
- Behavioral Intelligence — Intent scores, frustration detection, engagement metrics, churn risk (not available in GA4)
Custom Dashboards
Recreate any custom GA4 explorations using the ClickStream dashboard builder:
- Navigate to Dashboards > Create New
- Add widgets for each metric you tracked in GA4
- Set up date comparisons (ClickStream supports unlimited date ranges — no 14-month limit like GA4)
- Configure automated email reports to match your GA4 reporting cadence
Data Export
ClickStream exports data in Parquet format from managed R2 infrastructure for data warehouse integration:
// Export config (set in dashboard)
{
format: "parquet",
destination: "r2://clickstream-managed/exports/",
schedule: "hourly",
retention: "unlimited" // GA4 limits to 14 months
}
Phase 4: Remove GA4 (Week 5-6)
Week 5-6Once you have validated ClickStream is your source of truth, remove GA4 to reduce page weight and eliminate data leakage to Google.
Step 1: Export Historical GA4 Data
Before removing GA4, export any historical data you need:
- Use the GA4 BigQuery export to save raw event data
- Export custom reports as CSV from the GA4 interface
- Screenshot any dashboards you want to reference
Step 2: Remove the GA4 Script Tag
Delete the Google Analytics script tag from your HTML:
<!-- REMOVE this entire block -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');
</script>
Step 3: Remove GTM Container (If Applicable)
If you were using Google Tag Manager primarily for GA4, evaluate whether you still need it. ClickStream does not require GTM.
Step 4: Remove GA4 Custom Event Code
Search your codebase for any remaining gtag() calls and remove them. You should have already mapped these to ClickStream.track() in Phase 2.
# Search for remaining GA4 references
grep -r "gtag\|googletagmanager\|G-XXXXXXXXXX" --include="*.html" --include="*.js" .
Step 5: Verify Clean Removal
- Open DevTools > Network and verify no requests to
google-analytics.comorgoogletagmanager.com - Check that no
_gaor_gidcookies remain - Run a Lighthouse audit — you should see improved performance without the GA4 scripts
Historical Data Handling
ClickStream cannot import historical GA4 data directly (the data models are fundamentally different). However:
- Parallel tracking data — During Phase 1-3, ClickStream was collecting data alongside GA4. This provides 3-4 weeks of overlap.
- GA4 BigQuery export — Keep your BigQuery export for historical reference. You can query it alongside ClickStream data in your data warehouse.
- ClickStream retention — Unlike GA4's 14-month limit, ClickStream retains data indefinitely on managed infrastructure (you control retention policies).
Common Gotchas
- GTM triggers firing both tags — If using GTM, ensure you remove the GA4 tag from the container, not just from your HTML. Otherwise GTM will re-inject the GA4 script.
- Consent manager still referencing GA4 — Update your CMP configuration to remove GA4 from the "analytics" category and add ClickStream instead.
- Server-side GA4 integration — If you use the GA4 Measurement Protocol for server-side events, replace those API calls with the ClickStream Server SDK.
- GA4 audiences in Google Ads — If you use GA4 audiences for ad targeting, you will need to build equivalent audiences in your ad platforms using ClickStream's Parquet exports or direct integrations.
- Session definition differences — GA4 uses a 30-minute timeout and resets sessions at midnight. ClickStream uses a configurable timeout (default 30 minutes) with no midnight reset. Expect minor session count differences during parallel tracking.
Complete Migration Timeline
| Week | Task | Owner | Status |
|---|---|---|---|
| 1 | Set up tracking domain (CNAME + SSL) | DevOps / Engineering | — |
| 1 | Install ClickStream SDK alongside GA4 | Frontend Engineering | — |
| 2 | Validate parallel data collection | Analytics / QA | — |
| 2-3 | Map custom events (GA4 → ClickStream) | Frontend Engineering | — |
| 2-3 | Set up identity tracking (identify calls) | Frontend / Backend | — |
| 3-4 | Rebuild dashboards in ClickStream | Analytics / Marketing | — |
| 3-4 | Configure data exports (Parquet → R2) | Data Engineering | — |
| 4 | Stakeholder sign-off on ClickStream data | Analytics / Leadership | — |
| 5 | Export historical GA4 data (BigQuery) | Data Engineering | — |
| 5-6 | Remove GA4 tags from all properties | Frontend Engineering | — |
| 6 | Verify clean removal, update CMP, final QA | QA / DevOps | — |