Customer.io

Proxying the JavaScript client

You can proxy the client-side JavaScript (Analytics.js) and all tracking event requests through your domain. You might want to do this to deal with ad blockers or to keep your analytics requests from being blocked by firewalls.

How it works

When you load Analytics.js on your site, the script makes requests to Customer.io to load the library and to send calls. You can proxy these requests through your own domain, making all Customer.io requests look like first-party requests to your own domain. This can help you avoid problems with ad blockers or firewalls that don’t play nicely with third-party domains or requests.

This page shows how to set up a custom domain that proxies to cdp.customer.io in Amazon CloudFront, but you can apply these principles to most modern content delivery networks (CDN). You’ll also need to add a CNAME record to your DNS settings and update your code to point to your new domain.

Ad blockers and the /analytics-js/ path

Some filter lists, including EasyPrivacy, which many ad blockers turn on by default, block any URL whose path contains /analytics-js/, even on your own domain. A proxy that passes paths through unchanged, like the CloudFront setup on this page, keeps paths like /v1/analytics-js/snippet/, so these lists still block those requests.

If you need to reach visitors who use these lists, use the npm package and map your proxy to paths that don’t contain /analytics-js/. For example, set cdnURL to https://<YOUR-PROXY-HOST>/cio and apiHost to <YOUR-PROXY-HOST>/cio/v1, and have your proxy forward /cio/* to cdp.customer.io/* with the /cio prefix removed. The CloudFront steps on this page don’t rewrite paths, so you need to add that rewrite yourself, for example with a CloudFront Function. The SDK then requests its settings from /cio/v1/projects/<writekey>/settings and sends calls to /cio/v1/. If you use web push, the service worker loads its latest code from https://cdp.customer.io/v1/analytics-js/cio-webpush-sw-runtime.v1.js (or cdp-eu.customer.io) unless you set the web push plugin’s runtimeUrl option. Set runtimeUrl to a path like /cio/cio-webpush-sw-runtime.v1.js and also map that path to /v1/analytics-js/cio-webpush-sw-runtime.v1.js, since the prefix-strip rule can’t reach that file without /analytics-js/ in the path.

The snippet loads some of its files from /v1/analytics-js/ on the host that serves it, and you can’t change that path, so these lists can still block the snippet behind a proxy. The npm package also loads device-mode destinations from /v1/analytics-js/actions on your cdnURL host, so these lists block those destinations too.

Prerequisites

To set up a custom domain, you need:

  • Access to your site DNS settings
  • A content delivery network (CDN) you can serve assets from
  • Access to your CDN’s settings
  • A security certificate for the proxy domain

If you have trouble setting up your proxy, you’ll need to contact your IT department for help. We don’t have access to your domain resources to help you configure a custom proxy.

Set up a custom proxy with Amazon CloudFront

As a part of this process, you’ll set up two CloudFront distributions: one for the JavaScript host and one for our Pipelines API. You’ll also need to add a CNAME record to your DNS settings for each.

Proxy the JavaScript host

  1. Log in to the AWS console and go to CloudFront.

  2. Click Create Distribution and configure the distribution settings.

    1. In the Origin section set:
      • Origin Domain Name: cdp.customer.io
      • Protocol: HTTPS only
    2. In the Default cache behavior section, set:
      • Viewer protocol policy: Redirect HTTP to HTTPS
      • Allowed HTTP Methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
    3. In the Settings section, set:
      • Alternate domain name (CNAME): cioanalytics.<yourdomain>.com
      • Custom SSL certificate: Select an existing or new certificate and validate your authorization to use the Alternate domain name (CNAME) value. For more information, see Amazon’s documentation Requirements for using alternate domain names.

  3. Click Create Distribution. Take note of the Domain Name for use in the next step.

  4. Go to your domain registrar and add a new “CNAME” record.

  5. Set values for these fields:

    • Name: As a part of this process, you should use a name that makes it clear what you use the subdomain for, like analytics.mysite.com.
    • Value: The Domain Name value from CloudFront.

  6. Save your record. This might take some time to take effect, depending on your TTL (Time To Live) settings.

You should verify that you’ve set up the record correctly. You may want to make a curl request to your domain to verify that the proxy works.

Add the proxy to your code

After you set up a proxy, you’ll need to add your new proxy address to your code. These instructions depend on whether you use our Client-side JavaScript snippet or the Node.js library.

Client-side JavaScript snippet

If you use our JavaScript client, you need to modify the cioanalytics.js snippet inside your website’s <head>.

You’ll need to make two changes inside the declaration of the analytics.load function. We’ve highlighted the changes in an example below that’s formatted for readability.

  1. Change the t.src parameter in the snippet to point to your proxy host.
  2. Add an analytics._cdn property to the snippet containing your proxy host.
HTML
<script>
! function() {
  var i = "cioanalytics",
    analytics = (window[i] = window[i] || []);
  if (!analytics.initialize)
    if (analytics.invoked) window.console && console.error && console.error("Snippet included twice.");
    else {
      
      ...

      analytics.load = function(key, e) {
        var t = document.createElement("script");
        t.type = "text/javascript";
        t.async = !0;
        t.setAttribute('data-global-customerio-analytics-key', i);
        t.src="https://<YOUR-PROXY-HOST>/v1/analytics-js/snippet/" + key + "/analytics.min.js";
        var n = document.getElementsByTagName("script")[0];
        n.parentNode.insertBefore(t, n);
        analytics._writeKey = key;
        analytics._loadOptions = e
        analytics._cdn = "https://<YOUR-PROXY-HOST>";
      };
      
      ...

    }
}();
</script>

To proxy API calls that typically go to cdp.customer.io/v1, you’ll set integrations['Customer.io Data Pipelines'].apiHost to your proxy address.

JAVASCRIPT
window.cioanalytics.load("<MY_WRITE_KEY>", {
  integrations: {
    "Customer.io Data Pipelines": {
      apiHost: "YOUR-PROXY-HOST/v1",
    },
  },
});

npm instructions

If you use our Node.js library and want to proxy requests through your domain, you need to:

  1. Update the cdnURL setting.
  2. Proxy tracking calls that typically go to cdp.customer.io/v1 to your API host by configuring integrations['Customer.io Data Pipelines'].apiHost.
TS
const analytics = AnalyticsBrowser.load(
    {
      writeKey,
      // GET https://YOUR-PROXY-HOST/v1/projects/<writekey>/settings --> proxies to
      // https://cdp.customer.io/v1/projects/<writekey>/settings

      // GET https://YOUR-PROXY-HOST/next-integrations/actions/...js  --> proxies to
      // https://cdp.customer.io/next-integrations/actions/...js
      cdnURL: 'https://YOUR-PROXY-HOST'
    },
    {
      integrations: {
        'Customer.io Data Pipelines': {
          // POST https://MY-CUSTOM-API-PROXY.com/v1/t --> proxies to
          // https://cdp.customer.io/v1/t
          apiHost: 'YOUR-PROXY-HOST/v1',
          protocol: 'https' // optional
        }
      }
    }
  )
Updated October 27, 2026