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.
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:
- Graph: Checkouts per day
- Users View: Active customers (create a segment based on session activity)
- Funnel: Conversion Flow (Sign up, checkout, etc.)
- Retention: Use a key engagement metric (place order, add friend, comment, etc.)
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.
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 firstname.lastname@example.org if you have questions on how to best apply these conventions to your organization.
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:
- Web Event Visualizer (also includes React & Angular Apps)
- iOS Event Visualizer
- Android Event Visualizer
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:
View page: A pageview (MDN reference)
Click on: A click on an element (MDN reference)
Change on: A change in an
selectelement (MDN Reference)
Submit on: A form submission (MDN Reference)
Start Session: A session
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"> <label>Email</label> <input autofocus="autofocus" class="email" id="user_email" name="email" placeholder="Email Address" tabindex="1" type="email"> <label>Password</label> <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" /> </form>
Tag refers to the tag name (e.g.
<input> ). In line with standard CSS practices, in Heap, this is written as
A class name comes after the attribute
class=. Classes are prepended by a period, for example
An id comes after the attribute
id=. IDs are prepended by a hash, as in
An attribute is the part of the markup that is not an
class, such as
name. Attributes are contained in square brackets, as in
[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: .emailor
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.
* 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
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:
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.
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.
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 email@example.com for help defining event through the Visualizer or through the Events tab in Heap’s UI.
Unsure if you defined your event correctly? There are a couple of things you can check to gain confidence.
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
target text, or custom properties for custom events.
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 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.
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.