Web Event Visualizer


To use the Event Visualizer for websites and web apps, navigate to Define > Event Visualizer from within Heap. Click the text box to select from a menu of top viewed pages on your website or enter a URL in the text box. This will launch the event visualizer overlay on the selected page, so you can begin defining events.

To define new events, simply hover over and click on the element you'd like to define an event for. A pop-up will appear where you can review and update the definition of the event as needed before saving it.

Some helpful information is provided on this page which you can review to confirm that you are defining the right event, including:

Amount of clicks in the past week: Reference this number to make sure you’ve selected the right event. If it’s one that typically gets a lot of traffic, but this number is low, then you may need to adjust your event definition.

Number of matching elements on this page: If you intended to select an element that appears more than once, such as a list with multiple elements, you can check this number to confirm your selection is correct.

For example, you may wish to know when any element of a navigation bar is selected. You can hover over the navigation bar to select all of the elements in that space.

When defining an event, you can check the selector to confirm that it applies to the entire nav bar (#menu-header in the example above).

Selecting only one of the navigation bar elements will look like this in the event visualizer:

Definition: You can review the event definition contextually within the CSS of the page to ensure the scope of the event definition is correct.

Within the Edit Definition section, you can hover over each individual CSS element to see what it selects on the page. Clicking on an element adds it to your event definition, enabling you to further define your new event from this page based on what you want to capture.

Doing this won’t break your event definition - try clicking on different CSS elements and checking what gets captured to further optimize your new event.

You will also see warning messages for if you are defining an event that already exists in your Heap app, if there is no data associated with the event, or if the event matches what we know to be a bad pattern (such as being too wide in scope).

Once you’ve tailored your event definition to your needs, click ‘Next’ to name and categorize your new event. You can define an event in your personal or shared space, and add notes to give a deeper description of what this event is capturing.

Not familiar with CSS? Take our 23-minute Intro to HTML & CSS course to quickly ramp up to creating and managing your very own event definitions.

Best Practices

When defining events in the Event Visualizer via the web, we recommend the following best practices.

Always select the largest element possible. This includes all clicks that could occur inside the highlighted event.

Example: Capture All Clicks on Blog Post CTA

As an example, we may want to capture all clicks on a blog post on your homepage, including clicks on the title, image, and surrounding space within that element. To make sure all of these actions are captured, we will select the entire element when defining the event in the Event Visualizer.

If you define the event on only the title of the blog post, then you'll miss clicks on the other parts that also lead to that link.

Be careful when using dynamic CSS IDs or classes, which includes most IDs you see with a random string of numbers or classes (such as ember_12345) as these may limit the data captured to the extent that nothing appears in Heap. If you see no users have completed this action in your analysis, this means you probably have a dynamic CSS class or ID selected.

If too many elements are highlighted when you defined your event, you can narrow your definition by clicking on CSS elements to add them to your event definition.

If too few elements are highlighted, you can expand your definition to include the elements you want to capture by clicking on them within the edit definition section.

To better understand how CSS selectors work, check out our section on Defining Events in the Events Tab.

Example: Capture Clicks On Signup Wherever It Appears

Many users have elements that exist on multiple pages of their website, such as a sign up button. If an element has the same CSS hierarchy on all pages, then your event will be defined across all pages. If you only want to look at the event on a specific page, then make sure to check the 'Limit to URL' box when defining the event. This ensures that the event definition will only apply to the path, and not to all other pages where the same action is taken.

In this example, we highlight 'Sign Up' to define it as a new event. To make sure we are only tracking clicks on 'Get Started' on this specific page, we check 'Limit to URL'.

With that box checked, we don't have to worry about unintentionally capturing clicks on the same 'Sign Up' button on other pages.

Troubleshooting Common Errors

For errors using the Event Visualizer, see our web installation doc section I can't get the Event Visualizer to work. Why?

React & Angular Websites

Is your app built in a single page app framework, such as React or Angular? If so, be sure to write distinct classes or IDs or make use of data-attributes so that you can accurately define events based on those selectors.

Browser Compatibility

We only support the Event Visualizer for the latest version of Chrome on desktop. Mobile browsers are not supported. Other desktop browsers, including Firefox, Safari, Edge, and all others, are not supported.

If you are having any trouble with the Event Visualizer on Chrome, you should check to ensure you are on the latest version of Chrome. For steps to do so, see Google's support documentation.

Web Event Visualizer

Suggested Edits are limited on API Reference Pages

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