Installation
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","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 scriptheap.js
unsafe-inline
- allows execution of installation script tagunsafe-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:
- Option 1: use the wildcard:
Upgrading to New Version
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.
Classic SDK | New SDK | |
---|---|---|
Persistent Metadata State user id, session id, session properties, last event time, etc | stored in cookies | stored in cookies by default option to store in localStorage |
Ephemeral Metadata State page view id, page view properties | stored in memory | stored in memory |
Event Queue Event messages that are processed to be sent to heap | stored in memory | stored on localStorage |
Event Properties | stored in cookies | stored in cookies by default option to store in localStorage |
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 thanGET
. 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 anaddUserProperties
call to be consistent with the mobile SDKs.
- Metadata events are now also sent as separate events. Rather than having a
- 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
});
Updated 12 days ago