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

In your Cloudflare dashboard, go to Workers & Pages in the left sidebar
Click Create application, then Create Worker
Give it a descriptive name (e.g., usermaven-proxy) - you'll reference this later
Click Deploy to create the basic worker
After deployment, click Edit code button
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);
  },
};

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.

In your worker's page, click on the Triggers tab
Under the "Routes" section, click Add route button
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)
Click Add route

Step 3: Create a DNS record

Point your chosen subdomain to your Cloudflare worker.

In your Cloudflare dashboard, navigate to DNS → Records for your domain
Click Add record button
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
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

In your Cloudflare dashboard, go to Workers & Pages in the left sidebar
Click Create application, then Create Worker
Give it a descriptive name (e.g., usermaven-subdirectory-proxy)
Click Deploy to create the basic worker
After deployment, click Edit code button
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);
  },
};

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

Step 2: Add a route to your worker

In your worker's page, click on the Triggers tab
Under the "Routes" section, click Add route button
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
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

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

Usermaven dashboard verification

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

Checking worker logs

To debug issues:

Go to your worker in Cloudflare dashboard
Click on the Logs tab
Trigger the issue on your website
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 NOTneed 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

Issue	Symptoms	Resolution
404 error from worker/subdomain	Browser shows 404 when loading lib.js	• Ensure the worker route (Step 2) exactly matches your subdomain/subdirectory pattern• Verify the DNS CNAME record (Step 3) is correct and Proxied (orange cloud)• Check that your worker is deployed successfully
CORS error	Console shows cross-origin errors	• Ensure `data-tracking-host` in your snippet points to your proxy domain, not directly to Usermaven• Verify your proxy URL doesn't have trailing slashes where they shouldn't be
No Events Visible in Usermaven	Dashboard shows no new events	• Double-check the `data-tracking-host` value in your snippet• Confirm the Worker code correctly forwards to `events.usermaven.com`• Check the Worker logs in Cloudflare dashboard for errors• Verify your workspace key is correct
DNS points to prohibited IP	Error when creating CNAME record	• Leave the "Target" field blank initially when creating the CNAME• Cloudflare might auto-fill the correct `workers.dev` address• Try using the Worker's default domain from the Workers overview page
Script Loads but No Data	lib.js loads successfully but no events tracked	• Check browser console for JavaScript errors• Verify your workspace key is correct• Ensure `data-tracking-host` matches exactly your proxy URL
Worker route not working	404 errors despite correct setup	• Routes can take 1-2 minutes to propagate• Ensure the route pattern includes `/*` at the end• Check that the Zone selected matches your domain exactly

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.

Was this article helpful?