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:

Learn about how to organize your events into Categories here.

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. By default, the Event Visualizer picks the best selector to target the event you're trying to define. In the example below, that's an element with an href (a "link") attribute matching /signup. The other options here are to further limit the selector by the Target Text of the element, or to edit the CSS selector directly.

(NB: to better understand how CSS selectors work, see Defining Events in the Events Tab.)

Be careful when using conditional CSS IDs or classes (this includes most IDs you see with a random string of numbers or classes such as invalid). We try to avoid these whenever possible, but new cases may arise. If you see No users have completed this action, you probably have a conditional CSS class or ID selected.

If too many elements are highlighted at the same time, narrow your definition by clicking More Options and toggling things like Target Text, or by editing the CSS selector directly.

If too few elements are highlighted at the same time, expand your definition to the elements you want by selected Include Similar Elements or by editing the CSS selector directly.



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.



Defining Events in the Events Tab

We provide the Visualizer as a way to define events, but if you are familiar with your site's markdown you can always create events in our Events Tab. Heap attaches semantic meaning to the raw event data collected from the DOM. You can use HTML tags, CSS classes, Ids, and attributes from the markup of your site to define these events.

In the following examples, we'll be referencing this simple form:

<form accept-charset="UTF-8" action="/login" class="login signupform" id="new_user" method="post">
  <input autofocus="autofocus" class="email" id="user_email" name="email" placeholder="Email Address" tabindex="1" type="email">

  <input class="field with-reset" id="user_password" name="user[password]" placeholder="Password" tabindex="2" type="password" />

  <input class="button b-big" name="commit" tabindex="3" type="submit" value="Sign In" />

Tags, Classes, and Ids

A tag is the tag name (e.g. <input> ). In line with standard CSS practices, in Heap, this is written as input.

A class name comes after the attribute class=. Classes are prepended by a period, for example .email

An id comes after the attribute id=. Ids are prepended by a hash, as in #user_password.

You can combine multiple tags to create an event definition. For example, to define a change on event for the user email field in our form, the definition could be Change on input#user_email.

Hierarchical selectors are represented by a space between the tags, classes, and ids. Let's say you have more than one email form on a page: one to sign up, another to subscribe to a newsletter, and both email fields are defined the same way. You can use the form id to specify which form to target: Change on form#new_user #user_email which will limit the event to just the new user sign up form.


To use attributes in an event definition (here defined as attributes other than classes or ids, and includes things like name, type, and anything that starts with data-*) simply surround the attributes key and value with brackets. name="email" from the sample markdown above becomes[name=email] within Heap’s event creator.

You can also use simplified regex to match data attributes:

Please note, we do not capture the following attributes:

Combo Events (multiple selectors)

If there are multiple selectors that reference a given action(i.e. multiple sign up buttons), or if your markdown changes with a new engineering push you can maintain a continuous stream of data by using a combo event! To create a combo event you can either create a combo event based off of two discrete events by selecting Combo under source and each event you’d like to combine.

You can also separate multiple target elements with a comma. This means that a.b, c#d targets elements that match a.b or c#d. Referencing the example markdown above, we could create an event to capture the change on either input field by using #user_email, #user_name .

(NB: Snapshots do not currently work with combo events.)

Feel free to reach out to for any help defining event through the Visualizer or through the Events tab in Heap’s UI!

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.)