Error events in session replay

Overview

The Experience Analytics extension (which includes Session replay, Heatmaps, and Error Analysis) enables you to collect error event data directly in Heap. With this error data you can answer key questions such as:

How many errors occurred over the last week?
What types of errors are most common?
Which users are seeing errors?
How are errors impacting particular user journeys?

Enabling Error capture

Navigate to Account > Manage > Replay & Heatmaps
Click Edit next to your website session replay configuration
Within the fly-out panel under General Settings, scroll down and click on the Error Capture section.

Within Error Capture you’ll see three switches for JavaScript Errors, API Errors, and Custom Errors. Activate or deactivate these switches to turn on or off collection of these specific types of errors. Click Save and continue when finished.

Custom errors need code implementation in addition to toggling it on, see the Custom errors section below.

Error event types

Looking for crash events?

Crash events are only available for mobile; see Crash events in session replay (mobile only)

JavaScript errors

JavaScript is processed by a user's browser when they visit a page on your website. If JavaScript code contains mistakes, a JavaScript error will occur. JS Errors are not always visible to users on your site's front-end, but when they are, users can encounter:

Error messages
Pages not loading at all
Long load times
Unresponsive CTAs
Empty dropdown menu

Heap collects a maximum of 20 JS Errors per page view including the following error properties:

Property	Description
Error Message	The descriptive message found within the error response.
Error Group ID	An auto-generated ID used to group similar errors together in order to streamline analysis.
Error After Clicks	The number of error after clicks.
JS Error File Name	The name of the JS file which caused the error.
JS Error Line Number	The line of the JS file which caused the error.
JS Error Column Number	The column number of the JS file which caused the error.

API Errors

Error analysis with API error monitoring tracks two types of HTTP-based APIs, sent by the user-agent (browser) to servers:

XMLHttpRequest API: The most commonly used API, which can be used to exchange data between a user-agent (browser) and a server.
Modern Fetch API: Similar to XMLHttpRequest APIs but with a more powerful and flexible feature set.

Heap collects a maximum of 20 API Errors per page view including the following error properties:

Property	Description
Error Group ID	An auto-generated ID used to group similar errors together in order to streamline analysis.
Error After Clicks	The number of error after clicks.
API Error Duration	The length of time (in ms) it took to receive the response.
API Error Endpoint	The URL endpoint destination of the API request.
API Error Status Code	The relevant error response status code (400-599 codes).
API Error Method	The request method, the two most common HTTP methods are “GET” and “POST”. GET requests data and POST sends it.

Custom Errors

NOTE: In addition to switching on the Custom errors toggle in your Product Analytics settings, you must also add javascript code to your website.

Custom errors can be located inside alert banners, pop-up windows, or inline in a form. This is most commonly used to capture text displayed on the user’s screen such as text messages in banners and pop ups or in a form field based on a user action.

Product Analytics collects a maximum of 20 Custom Errors per page view including the following error properties:

Property	Description
Error Message (Optional)	The descriptive message of the Custom Error. This is configured as part of the Custom Error tracking code. See below for more details on how to implement Custom Error tracking on your website.
Error Group ID	An auto-generated ID used to group similar errors together in order to streamline analysis.
Error After Clicks	The number of error after clicks.

JavaScript for sending custom errors to Product Analytics

To collect custom error messages, use the trackError command:

<script type="text/javascript">
   window._uxa = window._uxa || [];
   window._uxa.push([
    "trackError",
    "<MESSAGE>",
    {key: value, key: value, ...}
  ])
</script>

where:

<MESSAGE> is a string which contains the text displayed to end-users (max. 300 characters)
Optional: A JavaScript object with up to 5 key/value pairs to categorize the errors. Both the key and value should be string and can be up to 30 characters

Custom error examples

Send a custom error for a failing request, typed as an error from the system:

<script type="text/javascript">
 window._uxa = window._uxa || [];
 window._uxa.push(["trackError", "Could not get stock quantity", { type: "systemError" }]);
</script>

Send a custom error for incorrect user input with multiple attributes (type, severity, language):


<script type="text/javascript">
 window._uxa = window._uxa || [];
 window._uxa.push([
   "trackError",
   "140000 is not a valid postal code",
   {
     type: "formValidation",
     severity: "minor",
     lang: "english"
   },
 ]);
</script>

Removing personal data in error capture

It’s important to ensure you aren’t collecting personal data when enabling error event collection.

To learn how to remove personal data in API errors, refer to the following applicable guides:

Using error events in analysis

Once error event collection has been activated, any sites and/or pages where session replay is configured to be capturing data will automatically begin collecting error events as native events within Heap's analysis modules. The will allow you to use errors in a variety of different ways including:

Measure frequency of errors over time
Identify number of users impacted by an error
Segment users based on whether they experienced an error event
Leverage errors in funnels and journeys
Build Charts with Errors using Heap's CoPilot AI
Send errors to your data warehouse via Heap Connect

In this example below, we've created simple graph over time to show the number of daily API Errors containing the term "heap" to better understand which endpoints are causing the most issues:

FAQs

Does error collection require its own separate subscription?

No. Error collection is included within the Experience Analytics extension at no additional cost.

Can errors be collected retroactively?

No. Errors are only collected after collection has been enabled within the session replay configuration.

Can error collection be enabled without session replay capture?

Error collection and session replay capture will only be captured on the domains and subdomains defined in the "Tracked domains" section of the configuration settings (when error collection is turned on).

Session replay capture can separately be modified by changing the sampling rate slider. The sample rate of session replay capture does not impact error collection.

most relevant results

developer center results