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 support@heap.io 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 start defining events in the Event Visualizer, review the section specific to your platform below. To learn about the Event Visualizer for Android, see Android Event Visualizer.

Websites & Web Apps

To use the Event Visualizer, 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 in the Event Visualizer, 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.

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.

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.

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.

React & Angular Apps

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.

iOS Apps

This video provides a brief introduction to the Event Visualizer for iOS:

To use the Event Visualizer for iOS, navigate to Define > Event Visualizer from Heap. From here, connect to your app and follow the onscreen instructions to start defining events.

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: input#user_email.email.

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.


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

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 support@heap.io 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.

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.