Proxy Usermaven script with Cloudflare workers

This guide shows you how to set up “pixel white-labeling” (also called proxying) by routing Usermaven’s tracking script and data collection through your own domain. This improves data accuracy as ad-blockers are less likely to interfere with your analytics.

Prerequisites

• Your website must be using Cloudflare
• Cloudflare Workers Free plan (100,000 requests/day) is generally sufficient
• Access to your Cloudflare dashboard
• Your Usermaven workspace key

Choose your proxy method

You can proxy Usermaven through either:

• Subdomain: track.yourdomain.com (recommended for most users)
• Subdirectory: yourdomain.com/track (good if you prefer a single domain)

Important: Choose random-looking names like s1, dataflux, or metrics instead of obvious ones like analytics, track, or stats. Random strings are better at evading ad-blocker filter lists.

Method 1: Subdomain proxy (Recommended)

Step 1: Create the Cloudflare worker

1. In your Cloudflare dashboard, go to Workers & Pages in the left sidebar
2. Click Create application, then Create Worker
3. Give it a descriptive name (e.g., usermaven-proxy) - you’ll reference this later
4. Click Deploy to create the basic worker
5. After deployment, click Edit code button
6. Delete all the default boilerplate code and replace it with:

// Cloudflare Worker: usermaven-proxy
// This script proxies requests to Usermaven's script and event endpoints.
 
export default {
  async fetch(request) {
    const url = new URL(request.url);
 
    // If the request is for the Usermaven script (lib.js)
    if (url.pathname === '/lib.js') {
      url.hostname = 't.usermaven.com'; // Usermaven's official script host
      return fetch(url.toString(), request);
    }
 
    // For all other requests (like event tracking), proxy to the events host
    url.hostname = 'events.usermaven.com'; // Usermaven's event collection host
    return fetch(url.toString(), request);
  }
};

7. Click Save and deploy button

Note: If you use a custom path for Usermaven’s script (not /lib.js), update the if (url.pathname === '/lib.js') line accordingly. This Worker forwards all original request details (headers, method, body) to Usermaven.

Step 2: Add a route to your worker

This tells Cloudflare to send traffic from your chosen subdomain to the worker.

1. In your worker’s page, click on the Triggers tab
2. Under the “Routes” section, click Add route button
3. Configure the route settings:
   • Route: Enter your-chosen-subdomain.yourdomain.com/*
     • Example: s1.yourdomain.com/* or dataflux.yourdomain.com/*
     • The /* at the end is crucial - it tells Cloudflare to route all paths under this subdomain
   • Zone: Select your main domain from the dropdown (e.g., yourdomain.com)
4. Click Add route

Step 3: Create a DNS record

Point your chosen subdomain to your Cloudflare worker.

1. In your Cloudflare dashboard, navigate to DNS → Records for your domain
2. Click Add record button
3. Configure the CNAME record:
   • Type: Select CNAME from dropdown
   • Name: Enter your chosen subdomain (e.g., s1 or dataflux) - don’t include the full domain
   • Target: Enter your Worker’s default *.workers.dev address
     • Format: your-worker-name.your-account.workers.dev
     • Example: usermaven-proxy.johnsmith.workers.dev
     • You can find this in your Worker’s overview page or it might be auto-suggested
   • Proxy status: Ensure it’s Proxied (orange cloud icon) - this is critical
   • TTL: Leave as Auto
4. Click Save button

Troubleshooting Tip: If you encounter a “DNS points to prohibited IP” error, try leaving the CNAME target blank when first creating the record. Cloudflare sometimes auto-populates the correct workers.dev hostname automatically.

Step 4: Update your Usermaven tracking code

Modify your existing Usermaven tracking code to use your new proxy subdomain.

Important replacements to make:

• Replace your-chosen-subdomain.yourdomain.com with your actual subdomain (e.g., s1.yourdomain.com)
• Replace YOUR_USERMAVEN_WORKSPACE_KEY with your actual Usermaven workspace key

<script type="text/javascript">
  (function () {
    window.usermaven = window.usermaven || function () {
      (window.usermavenQ = window.usermavenQ || []).push(arguments);
    };
 
    var t = document.createElement('script'),
        s = document.getElementsByTagName('script')[0];
 
    t.defer = true;
    t.id = 'um-tracker';
 
    /* 👇 Update these two lines to use your proxy subdomain */
    t.setAttribute('data-tracking-host', 'https://your-chosen-subdomain.yourdomain.com'); // e.g., https://s1.yourdomain.com
    t.src = 'https://your-chosen-subdomain.yourdomain.com/lib.js';                      // e.g., https://s1.yourdomain.com/lib.js
 
    // --- Standard Usermaven attributes (ensure these are present) ---
    t.setAttribute('data-key', 'YOUR_USERMAVEN_WORKSPACE_KEY'); // Replace with your actual workspace key
    t.setAttribute('data-randomize-url', 'true');     // Optional: helps if /lib.js is aggressively blocked
    t.setAttribute('data-autocapture', 'true');       // Optional: for automatic event capturing
 
    s.parentNode.insertBefore(t, s);
  })();
</script>

Method 2: Subdirectory proxy

Step 1: Create the Cloudflare worker

1. In your Cloudflare dashboard, go to Workers & Pages in the left sidebar
2. Click Create application, then Create Worker
3. Give it a descriptive name (e.g., usermaven-subdirectory-proxy)
4. Click Deploy to create the basic worker
5. After deployment, click Edit code button
6. Delete all the default boilerplate code and replace it with:

// Cloudflare Worker: usermaven-subdirectory-proxy
// This script proxies requests from a subdirectory to Usermaven's endpoints.
 
export default {
  async fetch(request) {
    const url = new URL(request.url);
    
    // Define your proxy path (change this to match your chosen path)
    const proxyPath = '/analytics'; // Change this to your chosen path like '/metrics', '/data', etc.
    
    // Remove the proxy path from the URL before forwarding to Usermaven
    if (url.pathname.startsWith(proxyPath)) {
      url.pathname = url.pathname.replace(proxyPath, '');
      
      // Handle empty pathname
      if (url.pathname === '') {
        url.pathname = '/';
      }
    }
    
    // If the request is for the Usermaven script (lib.js)
    if (url.pathname === '/lib.js') {
      url.hostname = 't.usermaven.com'; // Usermaven's official script host
      return fetch(url.toString(), request);
    }
    
    // For all other requests (like event tracking), proxy to the events host
    url.hostname = 'events.usermaven.com'; // Usermaven's event collection host
    return fetch(url.toString(), request);
  }
};

7. Change /analytics in the code to your chosen path (e.g., /metrics, /data, /s1)
8. Click Save and deploy button

Step 2: Add a route to your worker

1. In your worker’s page, click on the Triggers tab
2. Under the “Routes” section, click Add route button
3. Configure the route settings:
   • Route: Enter yourdomain.com/your-chosen-path/*
     • Example: yourdomain.com/analytics/* or yourdomain.com/metrics/*
     • The /* at the end is crucial - it captures all requests under this path
   • Zone: Select your domain from the dropdown
4. Click Add route

Important: Make sure the path in your route exactly matches the proxyPath variable in your Worker code.

Step 3: Update your Usermaven tracking code

Find your current Usermaven snippet on your website and replace it with:

<script type="text/javascript">
  (function () {
    window.usermaven = window.usermaven || function () {
      (window.usermavenQ = window.usermavenQ || []).push(arguments);
    };
 
    var t = document.createElement('script'),
        s = document.getElementsByTagName('script')[0];
 
    t.defer = true;
    t.id = 'um-tracker';
    
    /* 👇 Update these lines with your subdirectory path */
    t.setAttribute('data-tracking-host', 'https://yourdomain.com/your-chosen-path'); // e.g., https://yourdomain.com/analytics
    t.src = 'https://yourdomain.com/your-chosen-path/lib.js';                       // e.g., https://yourdomain.com/analytics/lib.js
    
    // --- Standard Usermaven attributes (ensure these are present) ---
    t.setAttribute('data-key', 'YOUR_USERMAVEN_WORKSPACE_KEY'); // Replace with your actual workspace key
    t.setAttribute('data-randomize-url', 'true');     // Optional: helps if /lib.js is aggressively blocked
    t.setAttribute('data-autocapture', 'true');       // Optional: for automatic event capturing
 
    s.parentNode.insertBefore(t, s);
  })();
</script>

Important replacements to make:

• Replace yourdomain.com/your-chosen-path with your actual domain and path (e.g., yourdomain.com/analytics)
• Replace YOUR_USERMAVEN_WORKSPACE_KEY with your actual Usermaven workspace key

Verify your setup (both methods)

Browser verification

1. Navigate to your website in a browser
2. Press F12 or right-click and select “Inspect” to open Developer Tools
3. Click on the Network tab in Developer Tools
4. Reload your website page
5. In the Network tab, filter for lib.js or search for your proxy domain
6. You should see lib.js loading from your proxy URL with a 200 OK status

Usermaven dashboard verification

1. Go to your Usermaven workspace
2. Navigate to the Events Activity page
3. Confirm that new page views and events are appearing
4. Perform some actions on your website and verify they appear in Usermaven

Checking worker logs

To debug issues:

1. Go to your worker in Cloudflare dashboard
2. Click on the Logs tab
3. Trigger the issue on your website
4. Check for error messages in real-time logs

Important notes

No Pixel white-labeling verification needed

The “Verify” button in Workspace Settings → Pixel White-labeling is only required when you CNAME to whitelabel.usermaven.com (so Usermaven can issue an SSL certificate).

Since the Cloudflare Worker proxies traffic through Cloudflare’s own edge and SSL, you do NOT need to add or verify your proxy domain in that UI. Just deploy the Worker, create the DNS/route, and update the snippet.

SSL certificate handling

Cloudflare automatically handles SSL certificates for your proxy domain, so you don’t need to worry about HTTPS configuration.

Performance impact

The proxy adds minimal latency (typically 10-50ms) as requests are processed at Cloudflare’s edge locations worldwide.

Troubleshooting common issues

Need help?

If you encounter issues, please reach out to our support via in-app live chat or email support@usermaven.com. Including your proxy subdomain and a screenshot of your Worker route configuration will help us assist you faster.