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.)
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:
- Limit to current page: Restricts the event to just the ones that have occurred on the current page.
- Include similar elements: Defines an event more broadly so that it targets multiple similar elements. For example, you can use this to define a generic "Clicked navigation button" event that applies to all buttons within a navigation toolbar.
- More options: Use this to directly modify the underlying CSS selector of the event. You can use the auto-generated selector (by default the most specific selector available), or modify the selector directly for greater granularity and control over your definition. You can also toggle other out-of-the-box parameters like target text.
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!
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:
- Text in Element: Specify a DOM element selector. Then, each time someone interacts with the element defined in the event, the full text inside the first matching DOM element gets extracted, trimmed, and attached to the event as a property. Direct descendent selectors and pseudo-classes are supported in Snapshots for more fine-grained targeting.
$(event.target).attr('data-id')will attach the
data-idattribute of the target element each time the event occurs.
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.
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:
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.
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…