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
├── servic