First-Party Tracking with Cloudflare Workers

Set up a first-party proxy using Cloudflare Workers. This guide is for users on shared hosting (Hostinger, GoDaddy, Bluehost, etc.) who cannot set up server-side proxies.

Before You Start

Make sure you have:

• A Cloudflare account (free tier works perfectly) - Sign up here
• Your domain added to Cloudflare (see Step 2)
• Your Zenovay tracking code (found in Dashboard → Your Site → Settings)

Why Cloudflare Workers?

Cloudflare Workers run on Cloudflare's global edge network (300+ data centers). This means:

• Fast: Sub-50ms response times worldwide
• Free: 100,000 requests/day on the free plan (more than enough for most sites)
• Simple: No server to manage
• Reliable: 99.99% uptime

Step 1: Create a Cloudflare Account

If you already have a Cloudflare account, skip to Step 2.

1. Go to cloudflare.com
2. Click Sign Up (top right corner)
3. Enter your email address
4. Create a password (at least 8 characters)
5. Click Create Account
6. Check your email and click the verification link

Step 2: Add Your Domain to Cloudflare

1. Log in to your Cloudflare dashboard
2. Click Add a Site (big blue button)
3. Enter your domain name (e.g., yourdomain.com)
   • Don't include www. or https://
   • Just the domain: yourdomain.com
4. Click Continue
5. Select the Free plan and click Continue
6. Cloudflare will scan your existing DNS records - click Continue
7. Cloudflare shows you two nameservers like:
   • bella.ns.cloudflare.com
   • troy.ns.cloudflare.com
8. Copy these nameservers - you'll need them in the next step

Update Your Domain's Nameservers

Now you need to point your domain to Cloudflare:

1. Log in to your domain registrar (where you bought your domain):
   • GoDaddy: godaddy.com
   • Namecheap: namecheap.com
   • Google Domains: domains.google.com
   • Hostinger: hostinger.com
2. Find your domain's DNS or Nameserver settings
3. Replace the existing nameservers with Cloudflare's nameservers
4. Save the changes

Step 3: Create the Worker

1. In the Cloudflare dashboard sidebar, click Workers & Pages
2. Click the blue Create button
3. Click Create Worker
4. Give your worker a name: zenovay-proxy
   • Use only lowercase letters, numbers, and hyphens
   • No spaces allowed
5. Click Deploy

You'll see a success message. Now we need to add the proxy code.

Step 4: Add the Proxy Code

1. After deploying, click Edit code (or go to your Worker and click "Edit code")
2. You'll see a code editor with some default code
3. Select ALL the existing code (Cmd+A on Mac, Ctrl+A on Windows)
4. Delete it (press Delete or Backspace)
5. Copy and paste the following code:

// Zenovay First-Party Proxy Worker
// This proxies tracking requests through your domain to bypass ad blockers

export default {
async fetch(request) {
  const url = new URL(request.url);

  // Get the real visitor IP address (for accurate geolocation)
  const clientIP = request.headers.get('CF-Connecting-IP') || '';

  // Determine the target URL based on the request path
  let targetUrl;
  if (url.pathname === '/script.js' || url.pathname === '/z.js') {
    // Script requests go to the regular endpoint
    targetUrl = `https://api.zenovay.com/z.js${url.search}`;
  } else {
    // All other requests (events, settings) go through first-party endpoint
    targetUrl = `https://api.zenovay.com/fp${url.pathname}${url.search}`;
  }

  // Copy the original request headers
  const headers = new Headers(request.headers);

  // IMPORTANT: Forward the real visitor IP for accurate geolocation
  headers.set('X-Zenovay-Real-IP', clientIP);

  // Remove the Host header (we're proxying to a different domain)
  headers.delete('Host');

  // Handle CORS preflight requests
  if (request.method === 'OPTIONS') {
    return new Response(null, {
      status: 204,
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
        'Access-Control-Allow-Headers': 'Content-Type',
      },
    });
  }

  try {
    // Forward the request to Zenovay API
    const response = await fetch(targetUrl, {
      method: request.method,
      headers: headers,
      body: request.body,
    });

    // Add CORS headers to the response
    const responseHeaders = new Headers(response.headers);
    responseHeaders.set('Access-Control-Allow-Origin', '*');

    // Return the response to the visitor's browser
    return new Response(response.body, {
      status: response.status,
      headers: responseHeaders,
    });
  } catch (error) {
    // If something goes wrong, return an error
    return new Response(JSON.stringify({ error: 'Proxy error' }), {
      status: 502,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}
}

6. Click Save and Deploy (top right corner)
7. Wait for the "Worker deployed successfully" message

Step 5: Add Your Custom Domain

Now let's connect your Worker to your domain:

1. Go to your Worker in the Cloudflare dashboard
2. Click the Settings tab (not "Triggers" - it moved to Settings)
3. Scroll down to find Domains & Routes section
4. Click Add → Custom Domain
5. Enter your subdomain: z.yourdomain.com
   • Replace yourdomain.com with your actual domain
   • Keep the z. prefix exactly as shown
6. Click Add Custom Domain
7. Cloudflare will automatically:
   • Create a DNS record for z.yourdomain.com
   • Provision an SSL certificate (HTTPS)
   • This takes 1-2 minutes

Step 6: Test Your Worker

Before adding the tracking script, let's make sure the Worker is working:

1. Open a new browser tab
2. Go to: https://z.yourdomain.com/script.js
   • Replace yourdomain.com with your actual domain
3. You should see JavaScript code (a bunch of minified code)

Step 7: Add the Tracking Script to Your Website

Add this code to your website's <head> section:

<script data-cfasync="false">
window.ZENOVAY_TRACKER_CONFIG = {
trackingCode: 'YOUR_TRACKING_CODE',
apiUrl: 'https://z.yourdomain.com',
settingsEndpoint: '/settings'
};
var script = document.createElement('script');
script.src = 'https://z.yourdomain.com/script.js';
script.defer = true;
document.head.appendChild(script);
</script>

What to Replace:

Example with Real Values:

<script data-cfasync="false">
window.ZENOVAY_TRACKER_CONFIG = {
trackingCode: 'ZV_Q8U0GYD70WR',
apiUrl: 'https://z.mywebsite.com',
settingsEndpoint: '/settings'
};
var script = document.createElement('script');
script.src = 'https://z.mywebsite.com/script.js';
script.defer = true;
document.head.appendChild(script);
</script>

Where to Add This Code:

• WordPress: Use a plugin like "Insert Headers and Footers" or add to your theme's header.php
• Wix: Settings → Custom Code → Head Code
• Squarespace: Settings → Advanced → Code Injection → Header
• Shopify: Online Store → Themes → Edit Code → theme.liquid (in the <head> section)
• HTML files: Between the <head> and </head> tags
• Any CMS: Look for "Custom Code" or "Header Scripts" in your settings

Step 8: Verify It's Working

Check 1: Network Tab (Any Browser)

1. Open your website in Chrome, Firefox, or Edge
2. Press F12 (or Cmd+Option+I on Mac) to open DevTools
3. Click the Network tab
4. Refresh your website (Cmd+R or Ctrl+R)
5. In the filter/search box, type script.js
6. Look for a request to z.yourdomain.com/script.js

What you should see:

• Status: 200 ✅
• Domain: z.yourdomain.com (your domain, not api.zenovay.com)

Check 2: Firefox Strict Mode (Most Important!)

Firefox has the strictest tracking protection. If it works in Firefox, it works everywhere.

1. Open Firefox browser
2. Click the menu (☰) → Settings
3. Click Privacy & Security in the left sidebar
4. Under "Enhanced Tracking Protection", select Strict
5. Close Settings and visit your website
6. Open DevTools (F12) → Network tab
7. Refresh the page
8. Search for script.js - it should load with status 200

Check 3: Zenovay Dashboard

1. Go to app.zenovay.com and log in
2. Click on your website
3. Visit your website in another tab
4. Within 1-2 minutes, you should see the visit appear in your dashboard

Final Checklist

Before you're done, verify ALL of these:

• Worker deployed at z.yourdomain.com (responding with JavaScript code)
• Custom domain uses z. prefix (NOT analytics., metrics., etc.)
• Script tag includes data-cfasync="false" attribute
• window.ZENOVAY_TRACKER_CONFIG is set with correct trackingCode
• Both URLs in the script use your custom domain z.yourdomain.com
• Tested in Firefox with Enhanced Tracking Protection set to Strict
• Visits appearing in Zenovay dashboard

Troubleshooting

Worker Returns 522 or 524 Error

Cause: Timeout connecting to Zenovay API.

Solution:

1. Check that api.zenovay.com is accessible (visit it in your browser)
2. Verify there are no typos in the proxy code
3. Try redeploying the worker (Edit code → Save and Deploy)

Custom Domain Shows SSL Error

Cause: SSL certificate not yet provisioned.

Solution: Wait 1-5 minutes. Cloudflare automatically provisions SSL certificates. If it takes longer than 10 minutes, check that your domain's nameservers are correctly pointing to Cloudflare.

Script Loads But No Data in Dashboard

Cause: Usually a tracking code mismatch.

Solution:

1. Open your browser's DevTools Console (F12 → Console tab)
2. Look for any red error messages
3. Verify your trackingCode matches exactly what's in your Zenovay dashboard (case-sensitive!)
4. Make sure the website domain is registered in Zenovay

"Script executing" But Nothing Happens

Cause: The apiUrl in your config is wrong.

Solution: Make sure your window.ZENOVAY_TRACKER_CONFIG has the correct apiUrl:

apiUrl: 'https://z.yourdomain.com',  // Your actual custom domain

Geolocation Shows Wrong Location

Cause: Real IP not being forwarded to Zenovay.

Solution: Make sure your worker code includes this line:

headers.set('X-Zenovay-Real-IP', clientIP);

Firefox/Edge Still Blocking

Cause: You're using a blocked subdomain like analytics.* or metrics.*.

Solution: Change your custom domain to z.yourdomain.com. You'll need to:

1. Go to Workers & Pages → Your Worker → Settings
2. Delete the old custom domain
3. Add new custom domain: z.yourdomain.com
4. Update both URLs in your tracking script

Advanced: Multiple Websites

If you have multiple websites, you can use one worker for all of them:

1. Add multiple custom domains to the same worker:

   • z.website1.com
   • z.website2.com
   • z.website3.com

2. Each website uses its own tracking code:

<script data-cfasync="false">
window.ZENOVAY_TRACKER_CONFIG = {
  trackingCode: 'ZV_SITE1CODE',
  apiUrl: 'https://z.website1.com',
  settingsEndpoint: '/settings'
};
var s = document.createElement('script');
s.src = 'https://z.website1.com/script.js';
s.defer = true;
document.head.appendChild(s);
</script>

<script data-cfasync="false">
window.ZENOVAY_TRACKER_CONFIG = {
  trackingCode: 'ZV_SITE2CODE',
  apiUrl: 'https://z.website2.com',
  settingsEndpoint: '/settings'
};
var s = document.createElement('script');
s.src = 'https://z.website2.com/script.js';
s.defer = true;
document.head.appendChild(s);
</script>

Next Steps

• Custom Events - Track button clicks and form submissions
• Visitor Identification - Connect analytics to user accounts
• Troubleshooting - More help with common issues

Need Help?

If you're stuck:

1. Double-check each step above
2. Make sure you're using z.yourdomain.com (not analytics.* or metrics.*)
3. Test in Firefox Strict mode
4. Check the browser console for errors (F12 → Console tab)

Still stuck? Contact support at [email protected] with:

• Your domain name
• Screenshot of the Network tab
• Any error messages from the Console tab