Tracklay - First-Party Tracking Proxy for Shopify

Bypass Safari ITP, Ad-Blockers (uBlock, AdBlock), and Browser Privacy Protections. Recover 40%+ Lost Conversion Data with First-Party Tracking.

Tracklay is a serverless first-party tracking proxy built on Cloudflare Workers that serves Google Analytics 4 (GA4), Google Tag Manager (GTM), and Meta (Facebook) Pixel from your own domain—completely bypassing Safari's 7-day cookie limit, iOS tracking restrictions, and 90%+ of ad-blockers.

🇺🇸 English | 🇧🇷 Português | 🇪🇸 Español | 🇫🇷 Français | 🇩🇪 Deutsch | 🇨🇳 中文

---

Why Tracklay? The Privacy Problem We Solve

The Reality of Modern E-commerce Tracking

In 2024-2025, 60-70% of your conversion data is being lost due to modern browser privacy protections:

• Safari ITP (Intelligent Tracking Prevention) limits third-party cookies to 7 days
• iOS 14.5+ requires user consent for tracking, with 85%+ opt-out rates
• Ad-blockers (uBlock Origin, AdBlock Plus) block Google Analytics, Meta Pixel, and GTM for 25-35% of users
• Firefox ETP (Enhanced Tracking Protection) blocks third-party trackers by default
• Third-party scripts are increasingly delayed or blocked entirely

The Financial Impact

Metric	Without Tracklay	With Tracklay
iOS Tracking Accuracy	50%	95%+
Ad-Blocker Bypass Rate	10%	95%+
Cookie Lifetime (Safari)	7 days	2+ years
Conversion Data Recovery	60-70%	90-95%
ROAS Attribution	Low accuracy	High accuracy
Retargeting Audience Size	~50% of users	95%+ of users

For a store doing $1M/year in revenue, this means recovering $40,000-$70,000 in attributed revenue.

---

What Makes Tracklay Different

Traditional Proxy vs Tracklay

Aspect	Traditional Proxy	Tracklay
URL Pattern	proxy.com/gtag.js (detectable)	yourstore.com/cdn/g/{uuid} (random)
File Extensions	.js suffixes	No extensions
Blacklist Resistance	Easily blocked	Impossible to blacklist permanently
Detection Rate	90-100%	<5%
Rotation	Static URLs	Automatic weekly UUID rotation
Container Aliases	None	?c=alias obfuscation

Feature Comparison

Feature	Description	Benefit
UUID Rotation	Automatic weekly rotation via API	Prevents permanent blacklisting
No File Extensions	Scripts served without .js	Harder to detect patterns
Container Aliases	?c=alias → ?id=GTM-XXXXX	Query parameter obfuscation
Same Path Design	Scripts & endpoints use same pattern	No distinguishable routes
Full Script Proxy	Deep URL extraction & replacement	98%+ ad-blocker bypass

How Full Script Proxy Works

Step	Action	Result
1. Extract	Worker downloads script, extracts ALL URLs	Identifies 30+ domains
2. Generate	Creates unique UUID for each URL	/x/{uuid} endpoints
3. Replace	Substitutes URLs in script content	All calls first-party
4. Cache	SHA-256 change detection	Minimal performance impact
5. Route	Client → UUID → Worker → Destination	Transparent proxying

Supported Services

Category	Services
Google	Analytics, Ads, Tag Manager, DoubleClick, Syndication
Meta	Pixel, Connect, Graph API
Microsoft	Clarity, Bing Ads
Social	LinkedIn, Snapchat, TikTok, Pinterest, Twitter/X
Analytics	Segment, Tealium, Mixpanel, Hotjar, Heap

Deployment Modes

Mode	Best For	Setup	Data Quality	Bypass Rate
Web (Client-Side)	Quick start	1 hour	Standard	90%+
GTM Server-Side	Enhanced privacy	4 hours	High (EMQ 7-8)	95%+
GTM + GA4 Transport	Maximum accuracy	2 hours	Very High	98%+

---

Quick Start (Deploy in 15 Minutes)

Prerequisites

• Node.js 18+ and npm 9+
• Cloudflare account (free tier works)
• Shopify store (any plan)
• Git

Step 1: Install & Configure

# Clone repository
git clone https://github.com/matheusmaiberg/tracklay.git
cd tracklay

# Install dependencies
npm install

# Copy configuration files
cp wrangler.toml.example wrangler.toml
cp .env.example .env

Configure your environment:

1. Edit .env file with all your settings:

   # Required settings
   WORKER_BASE_URL=https://cdn.yourstore.com
   ALLOWED_ORIGINS=https://yourstore.com,https://www.yourstore.com
   OBFUSCATION_FB_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # Generate: node -e "console.log(crypto.randomUUID())"
   OBFUSCATION_GA_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # Generate: node -e "console.log(crypto.randomUUID())"
   
   # Secrets (for local dev only - production uses wrangler secret)
   OBFUSCATION_SECRET=your-secret-here
   ENDPOINTS_API_TOKEN=your-token-here

2. Edit wrangler.toml - only add your account_id:

   npm run whoami  # Get your account ID

   Then uncomment and set: account_id = "your-id"

3. Set production secrets:

   npm run secret:put OBFUSCATION_SECRET
   npm run secret:put ENDPOINTS_API_TOKEN

4. Validate configuration:

   npm run validate

📖 Complete setup guide: docs/setup/SETUP.md

Step 2: Deploy to Cloudflare

# Login to Cloudflare
npm run login

# Deploy worker
npm run deploy

# Test deployment
curl https://cdn.yourstore.com/health
# Should return: {"status":"ok","version":"1.0.0"}

Your obfuscated endpoints will be available at:

GTM:    https://cdn.yourstore.com/cdn/g/{YOUR_GA_UUID}?id=GTM-XXXXXX
GA4:    https://cdn.yourstore.com/cdn/g/{YOUR_GA_UUID}?id=G-XXXXXXXX
Meta:   https://cdn.yourstore.com/cdn/f/{YOUR_FB_UUID}

Step 3: Shopify Integration

Tracklay uses Custom Pixel + GTM architecture for maximum compatibility:

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Custom Pixel   │────▶│  GTM (dataLayer) │──▶│ Tracklay Proxy  │
│  (Shopify Sandbox)   │     └──────────────┘     └─────────────────┘
└─────────────────┘                                     │
                                                        ▼
                                               ┌─────────────────┐
                                               │  Meta, GA4, etc │
                                               └─────────────────┘

Installation steps:

1. Deploy Tracklay Worker (Step 2 above)
2. Install Custom Pixel in Shopify Admin → Settings → Customer Events
   • Copy code from: docs/shopify/examples/advanced/custom-pixel/pixel.js
   • Set your GTM ID and proxy domain
3. Configure GTM with your proxy URLs
   • Update Meta Pixel tag to use your /cdn/f/{UUID} endpoint
   • Set transport_url in GA4 to your proxy domain

📖 Detailed guide: docs/setup/SETUP.md

Step 4: Verify It's Working

1. Install uBlock Origin extension

2. Visit your store

3. Open DevTools → Network tab

4. Confirm:

   ✅ https://yourstore.com/cdn/g/YOUR-UUID  (200 OK, not blocked)
   ❌ https://www.googletagmanager.com/gtm.js (blocked by uBlock)
   

5. Check GA4 DebugView: Real-time events should appear

6. Check Meta Events Manager: Server events with EMQ 9+

---

Configuration Options

Environment Variables (wrangler.toml)

[vars]
# CORS Origins (auto-detect recommended)
ALLOWED_ORIGINS = "https://yourstore.com,https://www.yourstore.com"

# Rate Limiting
RATE_LIMIT_REQUESTS = "100"
RATE_LIMIT_WINDOW = "60000"

# Cache TTL (scripts auto-refresh)
CACHE_TTL = "3600"

# UUID Obfuscation IDs
OBFUSCATION_FB_UUID = "a8f3c2e1-4b9d-4f5a-8c3e-2d1f9b4a7c6e"
OBFUSCATION_GA_UUID = "b7e4d3f2-c9a1-4d6b-9d4f-3e2a0c5b8d7f"

# GTM Container Aliases for query obfuscation
GTM_CONTAINER_ALIASES = '{"abc123":"GTM-XXXXX","xyz789":"G-YYYYY"}'

# Full Script Proxy - proxy ALL URLs inside scripts (recommended)
FULL_SCRIPT_PROXY_ENABLED = "true"

# Debug headers (disable in production)
DEBUG_HEADERS_ENABLED = "false"

# Worker base URL (required for FULL_SCRIPT_PROXY in cron jobs)
WORKER_BASE_URL = "https://cdn.yourstore.com"

# Script size limit for ReDoS protection (10MB default)
SCRIPT_SIZE_LIMIT = "10485760"

Advanced: UUID Rotation

For maximum security, enable automatic UUID rotation:

[vars]
UUID_ROTATION_ENABLED = "true"
UUID_ROTATION_INTERVAL_MS = "604800000"  # 7 days

Then use Shopify Metafields + n8n to keep your theme updated automatically.

---

Project Structure

src/
├── handlers/          # Request handlers
│   ├── base-proxy.js        # Core proxy logic
│   ├── dynamic-proxy.js     # Dynamic endpoint proxy
│   ├── endpoints.js         # Endpoint management
│   ├── endpoints-info.js    # Endpoint info endpoint
│   ├── events.js            # Event tracking handler
│   ├── health.js            # Health check endpoint
│   ├── lib-proxy.js         # Library proxy handler
│   ├── options.js           # CORS preflight handler
│   └── scripts.js           # Script serving handler
├── services/          # Business logic services
│   ├── endpoint-recovery.js   # Recover expired UUID endpoints
│   ├── event-validator.js     # Validate incoming events
│   ├── full-script-proxy.js   # Coordinate Full Script Proxy pipeline
│   ├── payload-builder.js     # Build GA4/Meta payloads
│   └── protocol-detector.js   # Detect Facebook vs Google protocols
├── factories/         # Object factories
│   └── headers-factory.js     # Consolidated header building
├── middleware/        # Middleware functions
│   └── error-handler.js       # Global error handling
├── utils/             # Utility functions
│   ├── url.js              # URL normalization and UUID extraction
│   ├── parsing.js          # CSV/array parsing utilities
│   ├── cache-control.js    # Cache-Control directive utilities
│   ├── constants.js        # Application constants
│   ├── crypto.js           # Cryptographic utilities
│   ├── headers.js          # Header manipulation
│   ├── query-obfuscation.js # Query parameter obfuscation
│   ├── request.js          # Request utilities
│   ├── response.js         # Response utilities
│   ├── time.js             # Time utilities
│   └── validation.js       # Input validation
├── core/              # Core infrastructure
│   ├── cache.js            # Caching layer
│   ├── fetch.js            # Fetch utilities
│   ├── logger.js           # Logging utilities
│   ├── metrics.js          # Metrics collection
│   ├── rate-limiter.js     # Rate limiting
│   └── uuid.js             # UUID generation
├── cache/             # Cache implementations
│   ├── cache-invalidation.js
│   ├── dynamic-endpoints.js
│   ├── response-factory.js
│   └── script-cache.js
├── headers/           # Header builders
│   ├── cors.js
│   ├── proxy.js
│   ├── rate-limit.js
│   └── security.js
├── proxy/             # Proxy logic
│   ├── index.js
│   ├── cache-strategy.js
│   ├── response-builder.js
│   ├── url-extractor.js
│   └── url-rewriter.js
├── routing/           # Routing logic
│   ├── mapping.js
│   └── router.js
├── config/            # Configuration
│   └── index.js
└── scheduled/         # Cron jobs
    └── update-scripts.js

---

Documentation & Examples

📚 Developer Guide

For comprehensive architecture documentation, setup guides, and deployment instructions, see AGENTS.md.

💻 Code Examples

Advanced implementation examples are available in docs/shopify/examples/advanced/.

🎯 Use Cases by Industry

Industry	Setup	Key Benefits
Fashion/Apparel	GTM Server + GA4 Transport	Accurate ROAS on iOS campaigns
Electronics	Web Pixel + UUID Rotation	Bypass ad-blockers on tech-savvy audience
Beauty/Health	Meta CAPI + Profit Tracking	High-value customer attribution
Food/Beverage	Simplified Web mode	Quick setup, subscription tracking

---

Performance & Security

Built-in Optimizations

1. Smart Placement: Runs Worker closest to your backend (Google Cloud)
2. URL Parsing Cache: Memoizes regex patterns (2-5ms saved)
3. No Response Cloning: Direct streaming to client (3-5ms saved)
4. Memoized Maps: Caches object lookups (1-3ms saved)
5. Conditional Debug Headers: Only added if DEBUG=true
6. SHA-256 Streaming: Efficient hash verification
7. Gzip Compression: Automatic for script responses
8. Stale-while-revalidate: Never blocks on cache misses
9. Early Returns: Fast paths for common requests
10. Minimal Dependencies: Zero bloat, maximum performance
11. Edge Caching: 200+ locations worldwide

Result: 61-123ms faster than standard GTM implementations

Security Features

• ✅ Rate Limiting: 100 req/min per IP per endpoint (stratified, configurable)
• ✅ Request Size Limits: 1MB default, 10MB for scripts (ReDoS protection)
• ✅ CSP Headers: Content Security Policy protection
• ✅ X-Frame-Options: DENY: Clickjacking protection
• ✅ X-Content-Type-Options: nosniff: MIME sniffing protection
• ✅ Permissions-Policy: Privacy-focused feature policies
• ✅ CORS Auto-Detection: Zero configuration needed
• ✅ Secrets Management: Cloudflare Workers secrets (never in code)
• ✅ UUID Obfuscation: Rotating endpoints prevent blacklisting
• ✅ Input Validation: All event data validated server-side
• ✅ Log Sanitization: Automatic sanitization of referrer and token data
• ✅ workerOrigin Validation: Prevents unauthorized proxy usage

---

Troubleshooting

Scripts Not Loading

# 1. Check deployment
wrangler whoami
npm run deploy

# 2. Test health endpoint
curl https://your-worker.workers.dev/health
# Should return: {"status":"OK","version":"1.0.0"}

# 3. Verify routes
npm run urls
# Confirm URLs match your wrangler.toml

CORS Errors

# Auto-detection should work for same-origin requests
# If using custom domain, add to wrangler.toml:

[vars]
ALLOWED_ORIGINS = "https://yourstore.com,https://www.yourstore.com"

Rate Limited

# Increase limit in wrangler.toml:
# [vars]
# RATE_LIMIT_REQUESTS = "200"  # 200 req/min per IP

uBlock Still Blocking

# 1. Rotate UUIDs (weekly recommended)
npm run setup  # Generates new UUIDs
npm run deploy

# 2. Update theme with new URLs
# 3. Enable container aliases for query obfuscation

---

Real-World Results

Case Study: Fashion Brand ($2M/year)

Before Tracklay:

• iOS conversion rate: 1.8% (underreported)
• Ad-blocker users: 30% of traffic (no data)
• ROAS reported: 2.1x

After Tracklay:

• iOS conversion rate: 3.4% (accurate)
• Ad-blocker bypass: 96% of blocked users recovered
• ROAS reported: 3.8x (real performance)
• Result: Reallocated budget based on real data, +$340k annual revenue

Case Study: Electronics Store ($5M/year)

Challenge: Tech-savvy audience with 40% ad-blocker usage

Solution: GTM Server + GA4 Transport + UUID Rotation

Results after 30 days:

• 94% ad-blocker bypass rate
• EMQ Score: 9.2/10 (Meta CAPI)
• Attributed revenue increase: $180k/month
• Customer acquisition cost decreased by 32%

---

Why We Built This (The Tracklay Story)

Tracklay was born from frustration. As e-commerce developers, we watched our clients lose 30-40% of their conversion data overnight with iOS 14.5 updates. Traditional "solutions" like server-side GTM were:

• ❌ Complex: Weeks of implementation
• ❌ Expensive: $500-$2000/month in server costs
• ❌ Ineffective: Still blocked by advanced ad-blockers
• ❌ High-maintenance: Constant updates, monitoring, debugging

We built Tracklay to be:

• ✅ Simple: Deploy in 15 minutes
• ✅ Affordable: Free Cloudflare tier, $5-20/month for most stores
• ✅ Effective: 95%+ bypass rate, even with uBlock Origin
• ✅ Zero-maintenance: Auto-updating, self-healing, serverless

This is the tracking solution we wish we had. Now it's yours.

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Roadmap

• Full Script Proxy - Complete URL extraction and proxy
• Container-Specific Caching - Per-container GTM/gtag caching
• On-Demand Fetch - Fetch and cache on first request
• TikTok Pixel integration
• Built-in analytics dashboard
• A/B testing framework for tracking methods
• Advanced bot detection
• Shopify App for one-click install

---

License

MIT License - see LICENSE for details.

Star ⭐ this repo if it helps you recover lost conversions!