Reach out with questions, bugs, or suggestions. We'll respond ASAP. Your message is sent! We'll respond via email shortly.

Frequently Asked Questions

If you don't see your question in this FAQ, please send us an email at

How is Heap different from Google Analytics, Mixpanel, and other analytics tools?

The primary difference between Heap and other analytics tools is our ability to track events automatically. Google Analytics only tracks pageviews by default, while Mixpanel and other event-based tools don't capture anything by default. These other tools require you to write custom logging code for each and every user interaction you care about (e.g. a button click or a form submission). There are several other important differences, too. For a full overview, check out our comparison pages.

How does Heap define a session?

A session is a period of activity from a single user in your app or website. It can include many pageviews or events. For web, a session ends after 30 minutes of inactivity from the user. For iOS, a session ends after your app has been closed or has entered the background.

Also, 4 server-side events are priced the same as a single session. Server-side events are counted differently because they aren't associated with any sessions.

Can I use Heap and Google Analytics at the same time?

Yes, our web and iOS libraries will work just fine if Google Analytics or other third-party services are also installed.

Does Heap work well with single-page web apps built on Backbone, Angular, and other frameworks?

Yes! In fact, Heap works especially well for single-page web apps. It provides extra functionality that other analytics tools don't, such as automatically capturing all pushState and hashChange events.

How does the free trial work?

Heap is free as long as you stay under 5,000 sessions per month. When your 14-day free trial ends, we do a simple calculation to prorate your likely monthly session count. The formula is: (session_count/14)*30 = your expected monthly session count. If your expected session count is under 5,000 sessions, you'll be rolled over into a free account. If it is over 5,000 sessions, you will be prompted to either talk to Sales to discuss pricing, or to add our badge which gets you a free account as long as you stay under 50,000 sessions per month.

Don't worry - we will not drop or throttle your data if you exceed the limit! Unless you deactivate your account, we will continue tracking your data until you add the badge or sign up for a paid account.

I see session time in the List view but not in other parts of the app. How can I track time on a page or the average time per session?

While we calculate session time on the fly in List view, time isn't a metric we track in Heap so this isn't possible without access to the full data via Heap SQL. Our approach is focused on what your customers do on your site or in your product. This means you can focus on events that match your KPIs and find actionable insights to improve everything from user engagement to your bottom line.

Where time can be most useful is by analyzing how long it takes your customers to do specific actions—check out the Average Time Between query type in Graphs.

Does Heap work well with hybrid mobile frameworks?

Heap should work with Cordova on iOS out of the box, and on Android with some slight modifications. For Android add this line within /android/CordovaLib/src/org/apache/cordova/engine/


To work, setAcceptFileSchemeCookies(true) has to be run before CookieManager is instantiated. For example:

     public SystemCookieManager(WebView webview) {
            webView = webview;
            cookieManager = CookieManager.getInstance();

            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
                cookieManager.setAcceptThirdPartyCookies(webView, true);

If you use Crosswalk, Cordova and Ionic will work on Android if you add this line within platforms/android/src/org/crosswalk/engine/

      public XWalkCordovaCookieManager() {
            cookieManager = new XWalkCookieManager();      ///forces file cookies

If you have any questions about your specific use-case, please reach out to for help!

Does Heap support multiple projects on the same account?

Yes, you can create additional projects by going to the "Account" menu in the upper-right corner of your dashboard, and then going to "Settings > Projects." You'll be able to create new projects and development environments as needed.

Does Heap work with multiple domains or websites?

If you have a single business or project that spans multiple websites, Heap can still track users across those domains. For subdomains on the same domain (e.g. "", "", and ""), Heap will automatically tie together a user's activity across each subdomain. For separate domains (e.g. "" and ""), Heap will treat activity from the same user on two different domains as two different users (because of how browser cookies work). In this case, you can use the heap.identify API to bypass this and tie together a user's activity across different domains.

Can I tie together user data across browsers and devices?

If a user visits your website from two different browsers or devices, then by default, Heap will treat that user as two different users. This is due to how cookies work. However, you can solve this with the heap.identify API, which lets you tie together a user's activity across multiple browsers or devices. Heap's identify API even works between web and native mobile apps. If you have Heap installed on both your website and your native mobile app, the identify API can tie together activity on both platforms and associate it with the correct user.

How can I use Heap from within a Chrome extension?

If you're running into trouble with Chrome extensions, you may want to enable the forceSSL option when loading Heap. More information about the various options here.

Why doesn't my report in another tool match a similar report in Heap?

If you're trying to understand why data in Heap is not matching data in another tool, please check out how to resolve these discrepancies.

How do I get data out of Heap?

To connect Heap data with your own internal systems, or to run ad-hoc SQL queries against your Heap data, check out Heap SQL. Like Heap, it enables you to do powerful retroactive analysis on all of your events. Contact sales if you would like to learn more!

We don’t believe in vendor lock-in and you will always retain ownership of your data. If you ever decide to leave Heap we offer a one-time data export.

Why is the count in my funnel different from the count in my graph?

In Heap, a graph and a funnel are measuring two different things. While a graph is measuring an event count, a funnel is measuring the number of unique users who completed the action. For example, if six users clicked the 'sign up' button once, and two users clicked the 'sign up' button twice, the graph would show a count of 10 and the funnel would show a count of 8. The funnel also shows the user count over the entire time range, where a graph shows the totals per day or week even if unique users is checked.

What Content Security Policy directives are needed for Heap to work?

If you have a Content Security Policy, include these directives in your CSP for Heap to work correctly: script-src *:// *:// 'unsafe-inline'; img-src *://; style-src *://; connect-src *://; font-src *://;

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.

Can I use Heap and comply with data privacy legislation?

We aren't able to sign any agreement such as a BAA for HIPAA compliant customers or Model Contract Clauses for EU customers. We are not able to sign any agreement that would potentially modify our terms of service. To ensure we don't collect any PII or PHI, we need to be extremely cautious if your company is HIPAA or COPPA compliant, or needs to adhere to EU or privacy legislation. We are not responsible for ensuring your compliance by using Heap, and suggest consulting legal counsel to determine if using Heap complies with your local governing laws. At a minimum, the following steps need to be taken to ensure that you are compliant:

  1. We can drop any uniquely identifiable information such as IP address. We won't collect any other uniquely identifiable information, and we won't automatically capture information from any input fields. You must request this prior to installing Heap. Don't send us any PII or PHI via our Identify API.

  2. Enable disableTextCapture as part of the installation process, which will make sure we don't capture any sensitive information that you might include in the elements on your pages.

  3. Make sure to prevent us from tracking any elements on the page that might be sensitive in their entirety by using our heap-ignore attribute.

  4. You can always selectively exclude the Heap tracking snippet on pages that contain sensitive information if you'd rather ensure specific views or URLs are absolutely not tracked or recorded.

If in fact you do end up sending PII to us, please let us know immediately at as we will have to delete your data from our servers. Contact us with any additional questions.

Does Heap offer any advanced configuration options?

Yes, 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 with caution! If you're unsure about correct usage, please email us at


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

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, secureCookie can potentially affect the use of our identify API.

    heap.load("YOUR_APP_ID", {
      secureCookie: true

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. Note that setting this option will prevent the Snapshots feature from working. For limited disabling of text capture, heap-ignore may be sufficient.

    heap.load("YOUR_APP_ID", {
      disableTextCapture: true