To effectively analyze your data, it’s important to understand how users, sessions, and events are connected. The summary version is that when users visit your app, they conduct sessions during which they do pageviews and events. This results in a hierarchy of users > sessions > pageviews and events within Heap. Accordingly, data points from all of these interactions are classified into the following property types.
User-level properties are all attributes associated with a user, including touch properties, account information, business logic, and more. Since they are at the top of the hierarchy and thus carry through each session and event, user-level properties apply across the entire hierarchy. You can group your analysis by user-level properties in any analysis view, which allows you to compare conversion rates based on plan type, Industry, LTV, region, and A/B experiment, just to name a few.
Session-level properties include all attributes captured at the session level, such as the landing page, browser, referrer, and more. Since they are in the middle of the hierarchy, session properties also trickle down and exist at the event level.
Pageview-level properties include all attributes associated with a particular pagveiew (or screenview on native mobile SDKs) such as path, title, and domain. Snapshots created on pageview events will result in pageview-level properties, and these properties will trickle down to all events that occur on that page.
Event-level properties are all attributes associated with events, including last touch properties, target text, or context captured by snapshots, such as price or quantity. You can also create custom events, aka events sent in via our track APIs, to have additional metadata (SKU, Email Subject, Successful Charge, etc.) associated with your user interactions.
Because events are at the bottom of the hierarchy, these properties only apply to those specific events. When grouping by event-level properties, you have to select the event with the properties you would like to group by.
First Touch Properties vs. Last Touch Properties
A first touch property represents the very first time a user had that specific interaction within Heap, such as the first time they ever signed in. A last touch property is the opposite – they represent the most recent interaction.
Heap tracks all first touch properties as user-level properties. You can use these properties to segment or group users for analysis.
Heap captures all touches in addition to first and last, and attaches the relevant session-level properties to each event.
Identifying Your Users
So Heap captures all of this useful information about user interactions. But how do we know which users are which?
Our identify API allows you to pass along all the information about a user that you have collected, such as their email address or a unique ID you may have assigned in your app’s backend, to Heap so that it can be a part of your analysis. This can be any information that you want to be associated with your users, such as email address, account type, A/B experiment variation, business logic (number of users on the account, LTV, etc.) and more.
Implementing our addUserProperties API allows you to pass along any useful information you have about the users, including demographic information, plan type, company information, industry information, and more that will help you filter by this data in your analysis.
The more information you pass, the more you can narrow the definition for and understand a particular subset or segment of users. This enables you to complete a richer analysis of your users’ interactions with your product.
We do automatically capture several initial properties, listed in Autocaptured Data (the next article in this section). For more information on how to configure these APIs to manage identified users, see the Using Identify guide.
Managing Anonymous Users
Even if a user hasn’t logged in, your site or app might still have valuable information that you might want to attach to a user as a user-level property. Heap attaches a unique identifier to anonymous users, so you can still attach this information as a user-level property using the addUserproperties API. A great example of when to attach user-level properties to anonymous users is A/B testing. See the Using Identify guide for more details and use cases for capturing anonymous user interactions.
How Do Custom Events Fit into the Hierarchy?
You can send custom events to Heap via our track APIs. When track occurs on the client-side, the event will occur in the context of a session, complete with all of the metadata associated with our autocaptured events. Server-side events exist outside the context of a session, and only have the properties that you send via the API call.