🚧

If you are using v4, use this guide instead. If you are unsure of which version you are using you can check here.

Self-hosting Heap’s JavaScript tracking library is an advanced configuration option for those concerned with the security and performance of running JavaScript loaded from a third party.

Fetching the Heap bundle to save locally

❗️

In the snippets below, remember to replace YOUR_ENV_ID with the ID of the environment to which you want to send data. You can find this ID on the Account > Manage > Projects page.

To fetch your custom heap.js JavaScript file:

1. Go to <https://cdn.us.heap-api.com/config/{YOUR_ENV_ID}/heap_config.js>
2. Copy or Save this file to your local code repository. (Path A)
3. Download https://cdn.us.heap-api.com/v5/heapjs-static/{heap_version}/core/heap.js
   Check https://developers.heap.io/docs/heapjs-5-changelog for the latest available version
4. Copy or Save this file to your local code repository at path /v5/heapjs-stable/{VERSION}/core/heap.js (Path B)
   Ex. https://example.com/v5/heapjs-stable/5.2.8/core/heap.js
5. Install the modified snippet with custom path (see Installation)

Installation

Paste the following code snippet before your website’s closing </head> tag. This should replace the original heap.js snippet you’ve installed. This snippet contains a modification of the existing snippet that allows you to pass in a custom path instead of fetching heap.js from our CDN.

📘

We cannot guarantee visual labeling functionality on sites that self-host heap.js. If you find that the EV does not load, try updating your snippet to the latest version.

<script type="text/javascript">
  window.heapReadyCb=window.heapReadyCb||[],window.heap=window.heap||[],heap.load=function(e,t){window.heap.envId=e,window.heap.clientConfig=t=t||{},window.heap.clientConfig.shouldFetchServerConfig=!1;var a=document.createElement("script");a.type="text/javascript",a.async=!0,a.src="{PATH_A}";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(a,r);var n=["init","startTracking","stopTracking","track","resetIdentity","identify","identifyHashed","getSessionId","getUserId","getIdentity","addUserProperties","addEventProperties","removeEventProperty","clearEventProperties","addAccountProperties","addAdapter","addTransformer","addTransformerFn","onReady","addPageviewProperties","removePageviewProperty","clearPageviewProperties","trackPageview"],i=function(e){return function(){var t=Array.prototype.slice.call(arguments,0);window.heapReadyCb.push({name:e,fn:function(){heap[e]&&heap[e].apply(heap,t)}})}};for(var p=0;p<n.length;p++)heap[n[p]]=i(n[p])};
  heap.load("YOUR_ENV_ID",
     sdk:{
        domain: 'DOMAIN_IN_PATH_B' // ex. https://example.com
        version: 'VERSION_IN_PATH_B' // ex. 5.2.8
     }
  );
</script>

Checking for Updates

Finding your currently deployed version

If you open the browser console on your website and type heap?.getConfig?.().sdk?.version.

If you get an error, you’re likely on an older version, and should use this guide for self-hosting. If the output is something other than x.x.x, you are likely using an experimental version as part of a test or deployment.

The full version number is made up of two parts:

Semantic Heap Version

This is the current version of heap’s tracker. Given a version number form MAJOR.MINOR.POINT:

• MAJOR – May include new APIs, deprecate existing APIs, remove already-deprecated APIs, or change behavior of existing APIs. May add or remove event types, change browser support, or other changes that might not be backwards-compatible.
• MINOR – May include new properties on captured events, or other functionality that does not break backwards compatibility.
• PATCH – Minor Bugfixes made in a backwards-compatible manner.

Checking the available heap.js version

You can find the latest version available in the heap.js v5 Changelog

If you want to ensure the latest snapshots and integrations are always loading with the snippet, be sure to update your heap_config file in step 1 from Heap’s CDN when you make changes.