Reach out with questions, bugs, or suggestions. We'll respond ASAP. Your message is sent! We'll respond via email shortly.

Events and Segments

If you haven't installed Heap yet, take a look at our installation instructions first.

Once you've installed Heap, the first step is to define events and segments. Since Heap automatically captures user actions, you'll be defining most of these events within the Heap interface. Then, you'll be able to create reports like conversion funnels or graphs. For a comprehensive guide to defining events please read this document.

What is an Event?

Events are the basic building blocks of reports. An event is anything users do in your app: "Create Account," "Login," "Restart Game," or "Follow A Friend" are all examples of events.

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.

There are a few different ways to define events in Heap.

The Event Visualizer

The Event Visualizer is Heap's take on analytics integration. Instead of manually logging events within code, you can define events by simply clicking around your website or tapping through your iOS app. No coding knowledge is required.

Visualizer for web

When you first log into your Heap account, you'll be taken to the Visualizer tab. Clicking the text box will open a menu with a list of pages on your website. Choose a page, or enter a URL in the text box, and you'll be taken to a version of your site with the Event Visualizer overlay. (Note: for this to work, the page must have the Heap tracking code installed.)

Heap event visualizer - web dropdown

When clicking on an element, all you need to do in order to define the corresponding interaction is provide a name and click "Define Event." There are options to ensure you've pinpointed the right event:

Heap event visualizer - web modal

To verify that you've defined an event correctly, navigate to the Events tab and use our Analysis Preview tools.

For best practices and more information about defining events, check out our Defining Events Best Practices article.

Visualizer for iOS apps

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

When you 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! Heap event visualizer - web dropdown

Event Creator

The event creator gives you more fine-grained control over event definitions. You can specify the precise page path for a pageview event, a target CSS selector for a click event, or the name of an iOS action method event. If you want to define an event corresponding to when users view your Pricing page, you could do the following:

Here's another example. You can specify the CSS selector of a link, button, or other HTML element to define a click or form submission event. This could be what an event corresponding to clicks on a "Login" button might look like:

Now the "View Pricing Page" and "Click Login Button" events will be saved and named. Now, these events are ready to be used in reports like conversion funnels.

CSS selectors may include tagnames, ids, and classes. You can also specify hierarchical CSS selectors of the form div.a div.b input. Note the spaces in-between to delineate hierarchy.

Only tags, classes, and identifiers are supported in hierarchical CSS selectors. Direct descendent selectors (e.g. div.a > div.b), pseudo-classes, and other advanced CSS features are not yet supported when defining events. Direct descendent selectors and pseudo-classes are only currently supported in Snapshots.


You might want additional context around the events that Heap auto-captures. For example, if a user enters a search query, you might also want to know the actual search query they entered. If a user adds an item to their shopping cart, you might want to know the item name, star rating, and price of the added item.

Normally, you'd have to resort to custom tracking code. With Snapshots, however, you can snapshot relevant data on a page and attach them to events. No need to write or ship code!

To get started, just launch the Event Visualizer, select an element, and then choose "Add Custom Property". The following video demonstrates attaching a custom Price property to every Add to Cart event.

Alternatively, you can use Snapshots by going to the Event Creator, clicking "+ Set Property", and manually configuring snapshotted data for use in custom properties.

Custom properties are configured on a per-event basis. There are two ways to snapshot data:

Any changes to a custom property take effect in less than 5 minutes. Unlike auto-tracked event properties, custom properties are not retroactive.

Snapshot properties are triggered by a user's interaction with the CSS selector in the defined event. As a result, they are available to use in analyzing the events on which they were defined, but will also be applied to other defined events if another event definition uses the same selector.

Snapshots is not yet available for iOS.

Event Combos

Sometimes there are multiple ways to do the same action within your app. Or your markup has changed, but you don't want to lose track of your existing event. In such cases, you can combine multiple events into a single super-event.

In the example above, any time a user does a Share link - Facebook event or a Share link - Twitter, the action also gets counted as a Share link event.

Event combos are especially useful when your markup changes. Simply define an event matching the new markup, then create a new event combo containing both the old event and new event. Or if you have Heap on both Web and iOS, you can use event combos to combine identical actions on different platforms.

If you modify or delete any of an event combination's sub-events, the combination itself will change.


In addition to events, Heap lets you define segments. A segment is any subset of your users: "Active Users," "Canadian Visitors," "Frequent Buyers," and "People who signed up in January" are all examples of segments.

For example, you could define a segment called 'Big Spenders' for all users with greater than 10 purchases: Big spenders segment screenshot

Later, when analyzing graphs, you could limit the data to users who are Big Spenders, or compare the behavior of Big Spenders versus users not in the segment.

Time-bounded Segments

Time-bounded segments are a type of segment that allow you to define a segment in terms of whether a user has done a specific event within the last day, week, or month. This means that the segment's membership changes every day. These type of segments can be graphed using Size of Segment, or used as filters for other queries.

Let's look at an example. You could define an 'Active Users' segment as users who have logged in at least once within the last week. Time-based segment screenshot

Size of Segment The size of a segment is calculated at midnight each day, and if you graph this in prior week segment using Size of Segment, each day's data point will represent the number of users who logged in at least once in the 7 days leading to that point. With a in prior month segment, it's the number of users over the prior 30 days. In prior day is the past 24 hours.

Filter The segment's behavior changes when used as a filter. Unlike the above example, an in prior week segment filter is applied to the event being analyzed, and is calculated as the prior 7 x 24 hours (168 hours) from the moment the query is run. So, running a query for the Count of Sessions in the past month, filtered by users in our Active User segment is the same as saying, "Of all the users who have logged in at least once in the past 168 hours from now, show me the sessions they had each day in the past month".

Event and segment definitions are only the first step, though. The next step is to analyze your events and segments using funnels, graphs, retention, and more…