❗️

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 heapanalytics.com.

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

Requirements

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.

Setup

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 heapanalytics.com. 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 mydomain.com, then this could be heapdata.mydomain.com but not heapdata.someotherdomain.com. 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.

DNS

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 somerandomstring.cloudfront.net.

Heap.js

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

heap.load("<your_env_id>");

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

heap.load("<your_env_id>", {trackingServer: "<https://heapdata.mydomain.com"}>);

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: "<https://heapdata.mydomain.com"}>);