To effectively analyze your data, it’s important to understand how users, sessions, and events are connected in our data model. The summary version is this:
Multiple users can belong to an account. When users visit your app, they conduct sessions during which they do pageviews and events. This results in a hierarchy of account > users > sessions > pageviews and events within Heap.
In Heap, bits of metadata from user interactions are known as properties. Properties are classified into the following types based on their place in the data model.
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 pageview (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, event-level properties only apply to those specific events. When grouping by event-level properties, you have to select the event with the properties you’d like to group by.
First Touch Properties vs. Last Touch Properties
In addition to the property types above, Heap distinguishes between first touch and last touch properties based on when the interaction occurred in relation to the history of the user. Whether a property is first touch, last touch, or somewhere in between plays a role in how it fits into the data model.
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 group first-time users together into a segment, then analyze that segment to better understand your app’s new user experience. Heap also attaches relevant session-level properties to each event, which you can use in analysis to spot trends during sessions.
Identifying Your Users
So Heap captures all of this useful information about user interactions and organizes it into a user-based data model. But how do you distinguish between different types of users?
Our identify API allows you to pass along all the information about a user that you’ve 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 automatically capture a wealth of initial properties as listed in Autocaptured Data (the next article in this section). For more information on how to configure these APIs to manage identified users, see Using Identify.
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.