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.)
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:
- Organize your actions under parts of your product
- Use present tense for your event names
- 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:
- 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
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"> <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>
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
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
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
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:
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 email@example.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.
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
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:
- Graph: Checkouts per day
- List 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.)