Web

Added link to broader description on SSL.

Use this guide for complete steps to install Heap on the web. For mobile (iOS and Android), see our mobile installation guide. For all other platforms, click the 'Installation Guides' drop-down in the left navigation, or see the 'recommended reading' section at the bottom of this guide.

IMPORTANT

When using the install snippet below, remember to replace YOUR_APP_ID with the ID of the environment to which you want to send data. You can find this ID within your Account Settings under the Projects tab.

Installation

To get started with Heap, paste the following code snippet before your website's closing </head> tag.

<script type="text/javascript">
    window.heap=window.heap||[],heap.load=function(e,t){window.heap.appid=e,window.heap.config=t=t||{};var r=t.forceSSL||"https:"===document.location.protocol,a=document.createElement("script");a.type="text/javascript",a.async=!0,a.src=(r?"https:":"http:")+"//cdn.heapanalytics.com/js/heap-"+e+".js";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_APP_ID");
</script>

Using the Correct App ID

If you're installing Heap on both production and staging versions of your site, be sure to use the app ID from your production environment in Heap on the production version of your site, and the app ID from your staging environment in Heap on the staging version of your site. If you send staging data into your production environment (or vice versa), it will pollute the data in that environment.

Sensitive Data

If there's a sensitive element you don't want autocaptured, you can hide it from Heap by just adding the attribute heap-ignore. All descendant elements will also be ignored by Heap. For example, no events triggered on the element <input type='text' heap-ignore='true'> will be captured by Heap.

Additionally, setting disableTextCapture will prevent heap.js from capturing the text content of elements. See the disableTextCapture section of this doc to learn more.

Troubleshooting

Having trouble installing Heap? Here's a list of some typical things to look out for. If your issue isn't addressed here, please email us at support@heap.io.

I can't get the Event Visualizer to work. Why?

Adblockers, Blocking 3rd party cookies, Internal Firewall

There are a few reasons this might happen. The most common is content or ad blockers. These extensions or plugins can prevent Heap from loading the JavaScript files we need for the Visualizer. If this is happening, you'll usually see errors in your Developer Console. If you get the error screen, look at the tab to its left, where Heap is trying to load the target page. Open the Developer Console, and look for something like this following, along with a reference to cdn.heapanalytics.com:

Failed to load resource: net::ERR_BLOCKED_BY_CLIENT

Make sure that you whitelist *.heapanalytics.com in any and all ad blockers. A quick way to test if any ad blockers are preventing Heap to load on a page is to open your page in an incognito window.

In the same way adblockers can prevent Heap JavaScript from loading, so can blocking 3rd party cookies in your browser, or even at a firewall. Check your browser settings, or with your systems administrator, to see if this is causing problems.

Lastly, some content blockers (e.g. Ghostery) can prevent cookies from being sent to the server, regardless of whether the blocker is blocking Heap directly or not. In the Network Requests tab of the target page, you should see a request containing /login?redirect=%2Fjs%2Fved.js if this is happening to you.

Incorrect Heap snippet placement

The Heap snippet should be installed directly on the page just before the </head> tag. If loading the snippet in the <body>, it's possible that the snippet isn't getting loaded before the Visualizer times out.

Typos in the Heap snippet

If you received the snippet copy/pasted into an email, or other document, it's easy for typographical elements of the snippet to get reformatted. For example, ending up with curly double quotes instead of straight quotes, or + signs getting stripped. If in doubt, copy/paste the snippet directly from the developer documentation for your app.

Rocketscript

If you're using Cloudflare, it will try to load JavaScript with rocketscript, which compresses, concatenates, and defers any JavaScript on your web pages. It also prevents the Heap snippet from loading properly. If you are encountering this issue, see this Cloudflare thread for steps on turning rocketscript off for Heap.

Content Security Policy

When you see the Heap error message, Heap is actually trying to load the target page in the tab to its left. Go to that page and open your browser's dev console to look for any errors. If your Content Security Policy is blocking the Visualizer, you'll usually see errors in your Developer Console saying that the browser 'Refused to load the script https://heapanalytics.com/js/ved.js because it violates the following Content Security Policy directive'.

To fix this, include these directives in your Content Security Policy for the Event Visualizer to work correctly:

script-src *://cdn.heapanalytics.com *://heapanalytics.com 'unsafe-inline'; img-src *://heapanalytics.com; style-src *://heapanalytics.com; connect-src *://heapanalytics.com; font-src *://heapanalytics.com;

The first script-src is for the installation snippet and identify API (hence the two domains). img-src is for our collector, and the final three, style-src, connect-src, and font-src are for the Event Visualizer.

My snippet is installed but I'm not getting data. What gives?

Data Latency

We open your Heap dashboard once data from your users hits our servers so you're not faced with an empty page. Usually this happens in a matter of minutes, but sometimes it's longer. We call this latency. Normal latency is under 30 minutes. Anytime beyond this, please feel free to contact us at support@heap.io.

Missing app_id

When copy/pasting the snippet, be sure you have code that includes your app_id in heap.load(). If you get the snippet from the install page after you sign up, or from our developer docs while logged in, this won't be problem. However, if you copy a version while logged out, you might end up with heap.load("YOUR_APP_ID") which won't work.

Incorrect app_id

If your Heap account holds more than one project or environment, make sure that the correct app_id is included in the <script> so that data is being sent to the correct place. To confirm the app_id in Heap, navigate to your Account Settings > Projects page. Each environment has an id in parentheses.

Double check that the Heap snippet here is the same as what's in app_id in the heap.load() call in the script on your site, or by typing heap.appid in the developer console.

Advanced Configurations

On the web, heap.load() can take an optional Javascript object as its second argument for additional configuration options. However, Heap's default settings cover most use cases, and implementing these settings can cause unintended behavior, so use them with caution! If you're unsure about correct usage, please reach out to support@heap.io.

forceSSL

Setting the forceSSL option forces heap.js to use SSL to send data to our collection endpoints. The primary use case is if you are using Heap in a Chrome Extension. forceSSL also can be required for the Event Visualizer to work properly with sites that are restricted via your company's VPN.

    heap.load("YOUR_APP_ID", {
      forceSSL: true
    });

secureCookie

Setting the secureCookie option means user cookies in heap.js will only be transmitted via SSL. If your site is entirely SSL, Heap defaults to sending data over SSL, so you do not need to enable this setting. If your site is a mix of SSL and non-SSL pages, using secureCookie can cause users to be duplicated between the secure and insecure parts of the site, so avoid using this if you have any non-HTTPS pages.

heap.load("YOUR_APP_ID", {
      secureCookie: true
    });

disableTextCapture

Setting the disableTextCapture option will prevent heap.js from capturing the text content of elements. By default, Heap does not capture the contents of input fields, but does capture text from other rendered page elements. For limited disabling of text capture, heap-ignore may be sufficient.

heap.load("YOUR_APP_ID", {
      disableTextCapture: true
    });

Snapshots & disableTextCapture

If you enable disableTextCapture, Heap will automatically drop all Target Text and potentially remove the metadata required for specificity in event definitions. We recommend adding Snapshots in these cases where text collection is necessary.

Content Security Policy (CSP)

If you have a Content Security Policy, include these directives in your CSP for Heap to work correctly:

script-src https://cdn.heapanalytics.com https://heapanalytics.com 'unsafe-inline' 'unsafe-eval'; img-src https://heapanalytics.com; style-src https://heapanalytics.com; connect-src https://heapanalytics.com; font-src https://heapanalytics.com;

The first 'script-src' is for the installation snippet and identify API (hence the two domains). 'img -src' is for our collector, and the final three, 'style-src', 'connect-src', and 'font-src' are for the Event Visualizer.

Other custom needs

If you have Heap installed on a single domain with hundreds of different projects or environments, please email us at support@heap.io.

Tracker Tech Specs

  • Load time: The Heap client-side script is hosted on Amazon AWS Cloudfront, a global CDN, which allows for extremely fast load times. The size of the script is minimal (less than 25kb).
  • Cross-browser testing: The Heap client-side data collection script is tested against all modern browsers, including mobile and desktop Chrome, mobile and desktop Safari, Firefox, and Internet Explorer 9+. Internet Explorer 8 is tested via version 11's compatibility mode.
  • Network impact: The Heap client-side script batches all autocaptured events and submits these requests to our servers every 2 seconds. This induces minimal network overhead, even for heavy usage applications.
  • Performance: Heap adds minimal CPU overhead (less than 0.1%), leaving application responsiveness virtually untouched.

Recommended Reading

For guides to install Heap on other platforms, see the following:

Implementing Heap on iOS & Android
iOS
Android
React Native
Kony
Electron
Third Party Installations
Self-Hosting Heap.js

Web


Added link to broader description on SSL.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.