Developer GuidesAPI ReferenceHelp CenterEngineering BlogCommunityOpen App

Self-Hosting Heap.js

Suggest Edits

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 heap.js to save locally

To fetch your custom heap.js JavaScript file:

  1. Go to https://cdn.heapanalytics.com/js/heap-{YOUR_ENV_ID}.js
  2. Copy or Save this file to your local code repository.
  3. Put on server at the path where self-hosting is configured
  4. Install the modified snippet with custom path (see Installation)

Fetch your custom heap.js JavaScript file at <https://cdn.heapanalytics.com/js/heap-{YOUR_ENV_ID}.js> Save this file to your local code repository.

❗️

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.

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.heap=window.heap||[],heap.load=function(e,z,t){window.heap.appid=e,window.heap.config=t=t||{};var r=t.forceSSL||"https:"===document.location.protocol,a=document.createElement("script");z=z||(r?"https:":"http:")+"//cdn.heapanalytics.com/js/heap-"+e+".js";a.type="text/javascript",a.async=!0,a.src=z;var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(a,n);for(var o=function(e){return function(){heap.push([e].concat(Array.prototype.slice.call(arguments,0)))}},p=["addEventProperties","addUserProperties","clearEventProperties","identify","resetIdentity","removeEventProperty","setEventProperties","track","unsetEventProperty"],c=0;c<p.length;c++)heap[p[c]]=o(p[c])};
    heap.load("YOUR_ENV_ID", "path/to/your/heap-{YOUR_ENV_ID}.js");
</script>

Checking for Updates

Finding your currently deployed version

Option 1: The first line of your heap.js JavaScript file will contain a version number in a comment.

Option 2: If you open the browser console on your website and type heap.version.installedVersion.

This will give you an object of form:

{
  heapJsVersion: "4.0.0",
  revisionId: "7ee97ac3319a0",
  installedVersion: "4.0.0+7ee97ac3319a0",
  supportedUntil: "2019-03-01T08:44:57.129Z"
}

Note: This method gives you more verbose information about your version, including support window dates.

Either of these methods will give you an installedVersion string with the form {Semantic Heap Version}+{13-digit customer hash}

Example:
//@preserve v4.0.0+1a2b3c4d5e6f7

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.

13-digit customer hash

This is a hash of your customized code (Snapshots + Any integrations that require JavaScript code)

A snapshot is JavaScript that can be added to your page to collect properties about events in addition to the data that we autocapture. See the Snapshots guide to learn more.

An integration is a third party source that we collect data from, i.e. Optimizely, VWO, or Google Optimize. Learn more about integrations by reviewing our Integrations guides.

You can expect this hash to change when you add, modify or delete a snapshot, add or delete an integration, or when there is an update to an integration’s code.

Checking the available heap.js version

You can check your current local version against the version available for you at this link (with your app ID instead of the placeholder): https://cdn.heapanalytics.com/js/heap-{YOUR_ENV_ID}.js. If the version number or hash in the first line do not match your local version and hash, you should download the new version to replace your existing file.

If you want to ensure the latest snapshots and integrations are always loading with the snippet, be sure to update Heap.js from Heap’s CDN on a regular cadence.

Changelog

For notable updates to the Heap.js library, see the heap.js Changelog.

Updated 11 months ago