What is an Event?

Events are the basic building blocks of reports. An event is any action associated with a user. Examples of events you can define in Heap include "Create Account," "Login," "Received Transactional Email," or "Follow A Friend".

In most other analytics tools, you need to write custom code to track events. However, Heap tracks everything automatically, which means defining events is a lot easier. It also means that every event definition is completely retroactive, since Heap has been recording everything from day one.

The best thing about events in Heap is that no matter how you define your event, all of 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 still readily accessible.

How Many Events Should I Define?

To get started analyzing your 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! When new questions come up, you can always define new events. All the data will still be there, even as you add definition further down the road.

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

Personal and Shared Events

In Heap, you can define personal and shared events. Personal events are ones that only appear in your Heap dashboard, and by default, are always added to your ‘Personal’ category. You can publish personal events to your shared space at any time.

Shared events can be accessed by your entire team. To stay organized, we recommend naming and organizing all shared events in a way that is helpful for your team, as detailed below.

Naming Conventions

Before you get into defining events, it's essential that you plan a consistent naming convention for your events and categories to help your team understand them. Some best practices for naming and organizing events include:

Organize your events into categories, which are essentially folders for events. A category can be a product, feature or page. We recommend using categories to organize actions your users take in different areas of your product. Examples:

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

To learn more about organizing events into Categories, see our Categories doc.

Use a standard naming pattern for defining events: we recommend using the Category - Event structure, as used in each of the examples above.

Choose a standard tense (either past or present) for your event names. For example, if you use present tense, you'll want to name your event 'Start Checkout' instead of 'Started Checkout' (past tense).

Add a note to the event to provide context about why it was created and what it's for. This is also helpful for describing differences between similar events, adding context for when an event is updated, noting if there is an exception that is not accounted for in this event, and more.

To add a note, navigate to Define > Events, click on the event to open up the event details, then click 'Add Note'. You can add multiple notes to the same event, and edit existing notes.

In addition to planning your event naming convention, we recommend that you also plan a consistent (and similar) naming convention for your reports to provide better context around the content of the report. The categorization of these reports highly depends on your organizational workflow, though we recommend including a product component or team name as a preface. Examples of reports with this naming convention:

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

Please don't hesitate to reach out to if you have questions on how to best apply these conventions to your organization.

Defining Events in the Event Visualizer

The Event Visualizer is Heap's simple point-and-click interface for defining events. Instead of manually logging events within code, you can define events by simply clicking around your website or app. No coding knowledge is required, though it is useful for refining your event definitions further.

To get started, see our platform-specific documentation:

Defining Events in the Events Tab

We provide the Event Visualizer as an easy way to define events without using code. However, if you are familiar with your site's markup, you can create events from the Events page within Heap

There are 5 types of events we capture in Heap out-of-the-box:

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

Tag refers to 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 an 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"] which uses 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:

To combine selectors in a hierarchy, uses a space between the tags, classes, and IDs. For example, 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, which would limit the event to the newsletter form.


The wildcard * character is fully supported in Pageview events, and partially supported in click/change/submit events. Partial support means the event will be usable in queries, but Snapshots do not work and the defined event will not render as such in the User's view or Live view.


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

You can also use simplified attribute selectors 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

React & Angular Apps

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

Combo Events

If you have two separate events you’d like to be able to view as one event, such as a ‘Free Trial’ event and a ‘Sign Up’ event that you’d like to view together as ‘Trial Signup’, you can combine them into a combo event.

To create a combo when editing an event, select 'Combo' under the Source drop-down. From there, select each event you’d like to combine.

Capturing Multiple Versions of an Event

If you need to update an existing event definitions to capture two versions of the same event that have different CSS selectors, you can combine them by separating the multiple target elements within the existing event definition with a comma. This means that a.b, c#d targets elements that match a.b or c#d. For example, if you're trying to select both the user email and user name in one event, you can 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 for help defining event through the Visualizer or through the Events tab in Heap’s UI.

Fact Checking Your Event Definitions

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

Check Analysis Preview

From the Events page, click on the event you'd like to check. In the event details, 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 Live View

Heap’s Live view provides you with a streaming, raw feed of all of your Heap events. You can use this page to QA your event definition by checking that when you take an action corresponding to your event definition, that event is captured in Heap.

To learn how to QA event definitions in the Live View, see the QA Events with Live View section of our Live View doc.

Deleting Events

To delete an event, from the Define > Events page, click the event to open up the event details, then click the trashcan icon in the top-right.

To delete multiple events at once, from the events tab, open the category of the event, click the checkbox next to the event, then click the trashcan icon next to "x events selected".

Note that custom events cannot be deleted from within Heap. We usually recommend hiding these events to prevent them from showing up anywhere within the app. This allows you to restore them later if you decide you want to report on them again.

Hiding Events

Note: only custom events can be hidden.

To hide a custom event, from the Define > Events page, click the event to open up the event details, then click the 'Visible' toggle in the top-right.

We can also delete these custom events on our end once you have verified that you are no longer sending any data in for them. Note that they will be restored if you later send data to that event definition again. Any requests to delete items from an account must come from an Admin on your team to ensure the security of your data.


Suggested Edits are limited on API Reference Pages

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