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

Defining Events

The best thing about Heap is that no matter how you define your event, all the correct data will be there. This means if you modify an event definition, define an event incorrectly, or want to add to your event - all the data is readily accessible. We encourage you to read this guide to better understand how best to define, organize and understand the events in Heap.

This recorded webinar provides best practices on how to define events in Heap.


(Total running time: 32 minutes.)

Naming Conventions

Before performing analysis in Heap, determining and maintaining a consistent naming convention is crucial to enable all members of your team to easily interpret events. In general, best practices around naming events are:

  1. Organize your actions under parts of your product
  2. Use present tense for your event names
  3. Specify differences between similar events by adding notes if an event changes, if there is a caveat, etc. using our event annotation feature

Following this principles, we suggest using this standard pattern for defining events in Heap:

Depending on the size of your application, a category for an event should be either a product, feature or page. Examples of this naming convention in practice may be:

We also recommend that you adopt a similar convention for report names to provide better context around the content of a report. The categorization of these reports highly depends on your organizational workflow, however we recommend including a product component or team name as a preface. The following may be examples of report names:

Please don't hesitate to reach out to our Customer Success Team if you have any questions around how to best apply these conventions to your organization!

Defining Events Using the Event Visualizer

There are a couple of best practices for defining events when using the Event Visualizer.

Always select the largest element possible. This will include all clicks on inside the highlighted event.

Like this: Not this:

Expand More Options to look at what has been selected. Be careful when using conditional CSS IDs or classes checked (this includes most IDs you see with a random string of numbers or classes such as invalid). Toggle these classes until you see the correct element defined, and the number seems accurate. If you see No users have completed this action, you probably have a conditional CSS class or ID checked. Here are some examples of classes that can affect numbers:

If too many elements are highlighted at the same time, narrow your definition to the element you want by expanding more options and selecting Text or Href. In most cases it is the best practice to select href to narrow down the result because the text of the link can change (for example, when the client-side is translated).



Many users have elements like a sign up button, that exist on multiple pages in their sites. If the element has the same DOM hierarchy on all pages, your event will be defined across all pages. If you only want to look at the event on a specific page make sure to select Limit to current page. This only applies to the path and not the hash or query parameters of the URL.

Fact Checking Your Definitions

Unsure if you defined your event correctly? There are a couple of things you can check to gain confidence.

Analysis Preview

Click an event you'd like to check in the Event tab. On the right, you'll see a summary of the count of events, a graph, and an Analysis Preview. This preview gives you an at-a-glance view of your event grouped by various properties, depending on the type of event. For this pageview event, which is defined as any page matching /examples/*, we can see the top 5 matching paths, verifying that our event is correct. Other events have different groupings, like href, target text, or custom properties for custom events.

Check the definition

Check the event definition make sure it uniquely identifies your event - whether it's by CSS ID, class, target text, or an href. Generic classes like .btn usually occur in multiple places on a site, so if that is the entirety of your definition, it may be too vague.

Check in the visualizer

Go to the page for which you you want to check events. Click Events in the top right corner of the Visualizer, and select the event you want to verify. All elements matching the event will be highlighted in red. If too many elements are highlighted, that may not be a good sign.

Use the List View

In the List view of Heap, create a Filter and set the parameters to has done your event in the prior day. Find the event in the in the List View and click on it. All of the details about this event will appear in a modal. Make sure this information is correct!

How many events should you define?

To get started analyzing data you only need to define a handful of events that will help you answer specific questions. There is no need to define your entire tracking plan upfront! As new questions come up, you can define new events. All the data will be there, even when you create a definition further along in the process.

Common first events include:

  1. Graph: Checkouts per day
  2. List View: Active customers (create a segment based on session activity)
  3. Funnel: Conversion Flow (Sign up, checkout, etc.)
  4. Retention: Use a key engagement metric (place order, add friend, comment, etc.)