❗️

Make sure to remove any existing install scripts for Heap on your site before installing the new version

Base Installation

To get started with Heap, paste the following code snippet before your website’s closing </head> tag. When using this snippet, remember to replace YOUR_APP_ID with the app ID of the environment to which you want to send data. You can find this ID on the Projects page.

<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="https://cdn.us.heap-api.com/config/"+e+"/heap_config.js";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_APP_ID"); 
</script>

Note that heap.js is always loaded over SSL.

❗️

If you’re installing Heap on both production and staging versions of your site, be sure to use the app ID that corresponds to the environment in Heap you want to send data to. If you send data to the wrong environment, it will pollute the data in that environment.

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.us.heap-api.com https://heapanalytics.com 'unsafe-inline' 'unsafe-eval'; img-src https://heapanalytics.com; style-src https://heapanalytics.com; connect-src https://c.us.heap-api.com https://heapanalytics.com; font-src https://heapanalytics.com;

• script-src
  • https://heapanalytics.com - loads the Visual Labeler script
  • https://cdn.us.heap-api.com - loads the Heap configuration script heap_config.js and SDK script heap.js
  • unsafe-inline - allows execution of installation script tag
  • unsafe-eval- required for Visual Labeler rendering
• img-src
  • https://heapanalytics.com - loads the Visual Labeler image assets
• style-src
  • https://heapanalytics.com - loads the Visual Labeler stylesheets
• connect-src
  • https://heapanalytics.com - used by Visual Labeler to fetch environment settings
  • https://c.us.heap-api.com - used by Heap SDK to send events
• font-src
  • https://heapanalytics.com - loads the Visual Labeler custom fonts

If you are unsure if you have any active CSPs, use this site to check: https://cspvalidator.org

Additional CSP directives for session replay

script-src 'unsafe-inline' t.contentsquare.net app.contentsquare.com; child-src blob:; worker-src blob:; img-src *.contentsquare.net; connect-src *.contentsquare.net; frame-src csxd.{crossdomain}

script-src 'unsafe-inline' t.contentsquare.net

The tracking tag comes from the domain t.contentsquare.net, so you need to authorize it. The tracking tag is usually loaded by a small inline script, so you need to allow loading scripts from ‘unsafe-inline’. Even if you load the tracking tag by other means, you’ll need ‘unsafe-inline’ for cross domain tracking, since our cross domain iframe uses inline scripts.

script-src app.contentsquare.com

app.contentsquare.com is not used by tracking tag to collect data. However, when creating a zoning from Contentsquare application, a script is injected in an iframe to assist in-page analysis and zoning creation.

child-src blob: / worker-src blob:

We use Web Workers, built from a blob URL containing the body of a function as a string. Origins of protocol blob: thus need to be authorized.

img-src _.contentsquare.net

We use calls to fake images to send tracked data to our servers. This is why our tracking subdomains need to be authorized sources for images. We use a wildcard since different subdomains could be added at any time. We discourage specifying exact subdomains.

connect-src _.contentsquare.net

We use XMLHttpRequest (XHR) to send tracked data to our servers. This is why our tracking subdomains need to be authorized sources for HTTP APIs. We use a wildcard since different subdomains could be added at any time. We discourage specifying exact subdomains.

frame-src csxd.{crossdomain}

If cross domain tracking is active, the tracking tag will need to load iframes to function. The tag will load one iframe for each domain for which cross domain tracking is active so you need to add them as in: frame-src csxd.domain1.com csxd.domain2.com.

Classic session replay CSP directives

If classic session replay is enabled, please add the following directives:

• If connect-src is used, the following rule must be added to load the configuration and to send the events:

connect-src *.auryc.com

• If worker-src is used, the following rule is recommended to leverage Web Worker for optimal performance:

worker-src blob:

• If font-src is used, the following rule is recommended to avoid errors due to harmless font files loaded by the Heap JS snippet (note: we are actively working on removing the code that causes these errors):

font-src *.auryc.com

• If script-src is used, one of the following rules must be added to load the JavaScript files:
  • Option 1: use the wildcard: *.heapanalytics.com
  • Option 2: If the wildcard is NOT supported, add these two specific rules:
    • https://cdn.heapanalytics.com/js/replay/libs/latest/auryc.lib.js
    • https://cdn.heapanalytics.com/js/replay/libs/latest/auryc.worker.js

Identifying Your Heap Version

To check the version you're currently using, open your browser's console and enter the following code:
heap?.getConfig?.().sdk?.version || heap.version.heapJsVersion.

If the console outputs 5.x.x, you’re using the latest version of Heap. If it shows a 4.x.x version, you’re on an older version, and we recommend upgrading to the latest version. If the output is something other than x.x.x, you are likely using an experimental version as part of a test or deployment.

Upgrading to Version 5

A site can be upgraded to the new SDK from the classic SDK by simply changing the current snippet to the Heap install code snippet above. When the new SDK loads onto the site, it will read any data within the cookies and copy them over to a new set of cookies or localStorage depending on the configuration option that has been set.

🚧

localStorage Notice

Access to localStorage is restricted by subdomain; persisting metadata and properties is not possible across subdomains if utilizing localStorage. For example, this means users and their properties will not track properly across test1.site.com and test2.site.com.

Beyond the storage of data, the new SDK utilizes all of the same core APIs as the previous iteration of the web SDK. This means that once a site has been updated to utilize the new SDK, any existing code written utilizing those APIs to identify users, addEventProperties, or other API functions will function exactly as they do today without any changes required.

Additional SDK Technical Information

• The new SDK utilizes POST requests: All HTTPS API requests are sent using POST rather than GET. This modern approach allows us to support a larger payload size.
  • Metadata events are now also sent as separate events. Rather than having a z=0, z=1, etc request, we now have separate requests for session, pageviews, and users. Pageviews and sessions will be sent as track requests, while user creation will be sent as an addUserProperties call to be consistent with the mobile SDKs.
• Events are Queued & Retried: All events are queued both in processing as well as before they are sent to the network layer. This provides us significantly better data quality. If requests are unsuccessful, they will be retried on subsequent page loads within the same subdomain.

Advanced Configuration

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 [email protected].

disableTextCapture

Setting the disableTextCapture option will prevent heap.js from capturing the text content of elements. By default, Heap doesn't capture the contents of input fields, but does capture text from other rendered page elements.

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

Note that disableTextCapture doesn't work on page titles. To selectively redact a page title, use the following snippet:

<title data-heap-redact-text='true'>

For more information on Heap's data privacy options, see How do I use Heap to comply with data privacy legislation?

For more information on ignore sensitive data, see Ignoring Sensitive Data and PII.

eventPropertiesStorage

This allows you to configure the storage medium for event properties, added via addEventProperties API. By default, event properties will be stored in cookies.

heap.load("YOUR_APP_ID", {
    eventPropertiesStorage: 'cookies' | 'localstorage'
});

metadataStorage

This allows you to configure the storage medium for metadata, including userId, sessionId, identity, lastEventTime and sessionProperties. By default, metadata will be stored in cookies.

heap.load("YOUR_APP_ID", {
    metadataStorage: 'cookies' | 'localstorage'
});

logLevel

Logging is essential for monitoring and debugging, and this option empowers you to tailor the amount of detail captured in logs. This option allows you to control the verbosity of logging. Additional levels will be available soon. By default logLevel will be set to none. We recommend keeping this set to none in production.

heap.load("YOUR_APP_ID", {
    logLevel: 'none' | 'trace'
});

enableSecureCookies

To enhance security and protect user privacy, it's advisable to set the enableSecureCookies option to true. This measure helps mitigate security vulnerabilities like Cross-Site Request Forgery (CSRF) and Cross-Site Script Inclusion (XSSI) attacks by constraining cookie behavior based on the request's origin. For the sake of backward compatibility, it's important to mention that we also provide support for the secureCookies option, which serves the identical function.

heap.load("YOUR_APP_ID", {
    enableSecureCookies: true | false
});

ingestServer

By setting the ingestServer option, you can direct requests to your own server, granting you greater control and customization over request processing. To ensure backward compatibility, we continue to offer support for the trackingServer option, which performs the same function.

heap.load("YOUR_APP_ID", {
    ingestServer: "YOUR_INGEST_SERVER"
});

disableSessionReplay

Setting the disableSessionReplay option to true will deactivate session replay for the designated page.

heap.load("YOUR_APP_ID", {
    disableSessionReplay: true | false
});

clearEventPropertiesOnNewUser

If clearEventPropertiesOnNewUser is set to true, event properties will be reset each time a new user is created. By default, event properties are only cleared after a period of 13 months.

heap.load("YOUR_APP_ID", {
    clearEventPropertiesOnNewUser: true | false
});

customEvents

❗️

Customers should be careful about using this client-side config. Some events (e.g. mousemove) are constantly firing and will degrade site performance.

The customEvents configuration allows for an array of events, each of which will be associated with an event listener linked to "autocapture." These events will function as manual track events, incorporating a hierarchy property when applicable.

heap.load("YOUR_APP_ID", {
    customEvents: Array<string>
});

disableInteractionEvents

The disableInteractionEvents feature disables autocapture of the designated interaction events. For instance, using disableInteractionEvents: ['click', 'submit'] will prevent the autocapture of click and submit events, while change events will still be captured.

heap.load("YOUR_APP_ID", {
    disableInteractionEvents: ['click','submit','change']
});

salesforceAura

When salesforceAura is set to true, we will delay the initiation of ShadowDOM capture until Salesforce Aura/Lightning Web Components initializes. We recommend customers who are using Salesforce Aura or Lightning Web Components to set this option true to prevent UI issues from arising from Heap and Salesforce Aura interactions.

heap.load("YOUR_APP_ID", {
    salesforceAura: true | false
});

disablePageviewAutocapture

Enabling the disablePageviewAutocapture setting will prevent automatic capturing of pageviews triggered by event listeners such as pushState, replaceState, popstate, and hashchange. However, it's important to note that pageviews occurring on page load and session expiration will continue to be captured automatically.

heap.load("YOUR_APP_ID", {
    disablePageviewAutocapture: true | false
});

compressCookies

Enable the compressCookies feature to reduce the size of cookies set by Heap. This can reduce the size of large cookies by upwards of 50%. Note that this has the side-effect of changing the composition of cookies that Heap sets, making them unreadable to humans.

The default value is false.

heap.load("YOUR_APP_ID", {
    compressCookies: true | false
});