Set up first-party data collection in Heap


Before making any changes to heap.js, be sure to confirm your CDN and DNS configurations with Heap support to ensure everything is configured correctly and data is flowing through to our servers.

First-party data collection allows you to direct all tracking requests to your own domain, so no requests go to

To avoid any loads from, you will also need to self-host heap.js.


Before getting started, make sure you have access to the following:

  1. The ability to configure DNS (e.g. domain names for your site).
  2. A CDN (Content Delivery Network) you can configure on your site’s domain. Examples of CDNs include AWS’s Cloudfront and Cloudflare.
  3. Access to edit the heap.js snippet that is deployed on all of your site’s pages.


CDN (Cloudfront)

Set up a “distribution” that will cause requests to data collection at your domain to be sent to Heap behind the scenes.

  1. Create a new distribution on Cloudfront or your CDN (content delivery network) of choice.
  2. Set the “Origin domain name” or equivalent to This is where the CDN will go to fetch data.
  3. Under “Alternate domain names”, add the domain to which you want to direct data. This must be a subdomain of the pages you are collecting data from: for example, if you’re collecting data at, then this could be but not This is where the CDN will expect to receive requests from.
  4. In other settings, ensure that “Forward Cookies” is set to “all” and that “Query string forwarding and caching” is set to “Forward all, cache based on all”. This is so that all necessary request data is forwarded to Heap’s servers.
  5. Click “Create Distribution” and take note of the domain generated for the CDN.


Set up the following CNAME record with your domain name provider:

  • Name: The “alternate domain name” from step (3) above.
  • Value: The CDN distribution domain name from the CDN setup. For example, with Cloudfront, it might


Your Heap snippet should have a line in it similar to:


You’ll need to add an additional argument specifying where Heap should send data going forward, where is the “value” from the DNS setup:

heap.load("<your_env_id>", {trackingServer: "<"}>);

If you are also self-hosting the Heap snippet, be sure to also include the path to where Heap.js is hosted (see our self-hosting docs for reference):

heap.load("<your_env_id>", "path/to/your/heap-{YOUR_ENV_ID}.js", {trackingServer: "<"}>);