Event Definition Best Practices

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.

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 these principles, we suggest using this standard pattern for defining events in Heap:

  • Category - Event

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:

  • Cart - Submit Purchase Form
  • Dashboard - Click Add Teammate
  • Sign Up Page - Change Email Address

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:

  • Marketing - Demo Request Conversion
  • Dashboard - Weekly Active Users

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

This video provides a brief introduction to the web 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 ember_12345). 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.



Using a Single Page App framework like React or Angular? Be sure to either write distinct classes or ids, or make use of data-attributes, so you can accurately define events based on those selectors.

Visualizer for iOS apps

This video provides a brief introduction to the iOS event visualizer:

When you first log in to your Heap account, you'll be taken to the Visualizer tab. Connect to your app and follow the onscreen instructions to start defining events!

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 markup you can always create events in our Events Tab

There are 4 types of event we capture in Heap out of the box:

In the following examples, we'll be referencing this simple form which lives at myawesomesite.com/signup:

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

An attribute is the part of the markup that is not id or class such as placeholder or name. Attributes are contained in square brackets, as in [name=email] or [placeholder="Email Address"]. Quotes are only required if the attribute contains a space.

In this example, you would define:

  • a pageview as View page: /signup
  • a click into the email field as Click on: .email or Click on: [placeholder="Email Address"] to use the attribute instead of the class.
  • a change in the password field as Change on: #user_password
  • a form submission as Submit on: #new_user

You can combine tags, classes, and ids in the same element by stringing them together. For example, Change on: input#user_email.email.

To combine selectors in a hierarchy, uses 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 and Change on: form#newsletter #user_email would limit the event to the newsletter 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:

  • [key] targets elements with a key attribute
  • [key=value] target elements with a key attribute that's value.
  • [key*=value] targets elements with a key attribute containing a value within it.
  • [key^=value] targets elements with a key attribute starting with value.
  • [key$=value] targets elements with a key attribute ending with value.

Please note, we do not capture the following attributes:

  • data-ember-action
  • data-react-checksum
  • data-reactid
  • input[value]
  • maxlength
  • onclick
  • onsubmit
  • style

Using a Single Page App framework like React or Angular? Be sure to either write distinct classes or ids, or make use of data-attributes, so you can accurately define events based on those selectors.

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 .

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

Feel free to reach out to support@heapanalytics.com 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 Users View

In the Users 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 Users 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 reports include:

  1. Graph: Checkouts per day
  2. Users 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.)