Heap's power comes from automatically capturing a wealth of user interactions in your app, which are classified as events and properties. This autocaptured data is organized into the hierarchy account > user > sessions > pageviews > events, where users belong to accounts, users have many sessions, sessions include pageviews, and during those pageviews, events occur.
Out-of-the-box, Heap provides a wealth of autocaptured events and properties to help you quickly get started with analysis. Reference the platform-specific sections below for the full list of all of the autocaptured data available when you install Heap.
This article only covers data brought in by Heap. For a list of data brought in by Heap Connect, see Heap Connect: Data Schema.
How does Heap define a session?
A session is a period of activity from a single user in your app or website. It can include many pageviews or events. On web, a session ends after 30 minutes of pageview inactivity from the user. On mobile, a session ends after 5 minutes of inactivity, regardless of whether the app’s background or foreground state.
Note that the default events and properties aren't modifiable. To add a new label for a default event or property, make a copy of it, add a label, then save it as a new event or property.
For information on what session replay captures, see What does session replay capture?
Choosing between autocaptured and snapshotted data
In cases where you're trying to decide whether to use an autocaptured property or a snapshot, we recommend going with an autocaptured property. For example, if you want to track search terms, and the search term shows up in the URL of the page that the search was conducted on, you can set up a property to capture that search term based on the autocaptured Path property instead of a snapshot. This is preferable because autocaptured data is retroactive and provides a wealth of additional data points to work with.
All Platforms
Events
An event is an interaction that a user has with your website or app. By default, Heap autocaptures the following types of events:
-
View page: A pageview (MDN reference) -
Click on: A click on an element (MDN reference) -
Change on: A change in aninput,textarea, orselectelement (MDN Reference) -
Submit on: A form submission (MDN Reference) -
Start Session: A session
When you first install Heap, your events page won't have any labels listed. However, the following events can be accessed via the analysis chart drop-downs (listed below in the 'Where it appears' column) to get you started with analysis right away.
| Event | Definition | Where it appears |
|---|---|---|
| Session | A session by a user. | In the Usage over time, Users, Retention, and Influence analysis data drop-downs. |
| Pageview | A pageview by a user. | In all of the analysis data drop-downs. |
| Rage Click | A user repeatedly clicking on one part of the page within a short timeframe. | In all of the analysis data drop-downs. Note that it is only available to accounts with paid plans. |
Because of the way Heap's data hierarchy works, all session-level properties are also passed down to these events. This means that, when conducting analysis on an event, you can modify the chart based on any session-level property, such as analyzing the session event and grouping the results by the platform session property.
User Properties
A user is exactly what it sounds like - a unique visitor to your site or app. On the web, a user maps directly to a unique client-side cookie. On iOS and Android, user state is stored in a local database (NSUserDefaults or SQL). If identified, a user maps to a unique identity.
User properties are bits of data associated with users. Heap provides the following user properties out-of-the-box for all platforms:
| Property | Definition |
|---|---|
| User ID | A randomly generated user ID that's used to identify a user in Heap. |
| Initial Continent | The continent that the user was identified as being in during the first session. |
| Date First Seen | The timestamp of when the user was first seen by Heap. |
| Initial Location | The initial city, region, and country the user was identified as being in during the very first session. |
| Initial City | The user's city as determined by their IP address during their very first session. |
| Initial Country | The user's country as determined by their IP address during their very first session. |
| Initial Region | The user's region as determined by IP address during their very first session. |
The following three properties are only available if you configure our APIs to capture an identity for your users.
| Property | Definition |
|---|---|
| The user's email address. If you are capturing this info via the addUserProperties API, this is where it will appear. | |
| Handle | The user's handle (also known as a username). If you are capturing this info via the addUserProperties API, this is where it will appear. |
| Identity | If you configure your Heap implementation to use the Identify API, this is where the user's identifier will appear. |
Session Properties
Session properties are bits of data associated with a session. Some notes about session properties:
- While you can create new event properties and user properties, you can't create new session properties.
- Because of the way Heap's data hierarchy works, all session-level properties are also passed down to events. This means that, when conducting analysis on an event, you can update the chart based on any session-level property, such as analyzing the session event and grouping the results by the platform session property.
Heap provides the following session properties out-of-the-box for all platforms:
| Property | Definition |
|---|---|
| Session ID | A randomly generated ID number. |
| User ID | The ID of the associated user. |
| Time | The timestamp of when the session began. |
| Platform | The user's operating system. |
| Device Type | The device type, either Mobile, Tablet or Desktop. |
| Country | The user's country, based on their geolocation data. |
| Region | The user's region, based on their geolocation data. |
| City | The user's city, based on their geolocation data. |
| Source | This indicates which Heap snippet or SDK the data was captured by: either Web, iOS, or Android. |
Geolocation properties are subject to change
All of our geolocation properties are subject to change by our service provider, Maxmind. Please see their Release Notes to check for recent changes to these properties.
Event Properties
An event is an interaction that a user has with your website or app. Event properties are bits of data associated with events.
Heap provides the following event properties out-of-the-box for all platforms:
| Property | Definition |
|---|---|
| Type | This can be any one of the following: view page, click, submit, change, with push state events registered as view page events. |
| Time | The time when the event happened. |
| User ID | The ID of the associated user. |
| Session ID | The ID of the associated session. |
| Target Text | The text of the event target. |
| Event ID | The ID of the event. |
Web
The following events and properties become available after you install Heap for the web. To get Heap for the web, see our Web Installation Guide.
Web User Properties
The following user properties are only available for web installations of Heap. Note that 'initial' refers to the very first time a user ever completed the action, and not the first time the user completed that action within a certain window.
| Property | Definition |
|---|---|
| Initial Landing Page | The first page the user landed on at the start of their very first session. |
| Initial Landing Page Hash* | The hash route of the first page of the user's very first session. |
| Initial Landing Page Query* | The query parameters of the first page of the user's very first session. |
| Initial Referrer | The web page or app screen that the user came in from during their very first session. |
| Initial UTM Source, Initial UTM Medium, Initial UTM Term, Initial UTM Content, Initial UTM Campaign | These are GA-based URL tags associated with the session's initial pageview. |
Initial Landing Page Hash & Initial Landing Page Query
*These properties were added into Heap on 3/18/2020. Because of the nature of these properties, no autocaptured data for these properties will be available prior to that date.
| Initial Browser Type | The browser of the user during their very first session. |
| Initial Browser | The browser the user came in on during their very first session. |
| Initial Device Type | The type of device the user accessed your site or app from during their very first session. |
| Initial Platform | The operating system used by the user during their very first session. |
Web Session Properties
The following session properties are only available for web installations of Heap.
| Property | Definition |
|---|---|
| Referrer | The webpage that linked to your site and initiated the session. If the user navigated directly to your site, or if the referral headers were stripped, then this value will appear as direct. |
| Full Referrer | The same as the referrer, though this contains the protocol, port, and path, if they exist. |
| Landing Page | The first page of the current session. |
| Landing Page Hash* | The hash route of the first page of the user's session. |
| Landing Page Query* | The query parameters of the first page of the user's session. |
| Browser | The user's browser. |
| UTM Source, UTM Medium, UTM Term, UTM Content, UTM Campaign | These are the UTM parameters in the query string of the first page of the user's session. |
*These properties are limited to 256 characters.
Referrer Truncation
The Referrer property is truncated to the domain by default, but you can access the Full Referrer by creating a formula property.
Full Referrer Truncation in Chrome 84
The release of Chrome 84 impacted the way that Full Referrer is captured. If one of your users was using Chrome 84 during their session, then the Full Referrer property will appear truncated in your Heap autocaptured data.
Web Event Properties
The following event properties are only available for web installations of Heap.
| Property | Definition |
|---|---|
| Target Tag | The tag name of the event target's DOM element, e.g. INPUT, DIV, or A. |
| Target ID | The ID of the event target's DOM element, e.g. #login. |
| Target Class | The class name of the event target's DOM element, e.g. .primary-btn. |
| Href | The href property of link. (for clicks on anchor tags). |
| Previous Page | The previous page visited in this session. |
| Domain | The current domain, including the subdomain, e.g. blog.heap.io. |
| Hash | The part of the current URL following the hash sign, e.g. #install for heapanalytics.com/docs#install. |
| Path | The part of the current URL following your domain, e.g. /category/ for https://help.heap.io/. |
| Query | The query params of the page's current URL, e.g. ?utm_id=1234 for heapanalytics.com?utm_id=1234. |
| Title | The title of the current HTML page. |
| Hierarchy | The full hierarchy of the event target on click, change, and submit events. Note: Heap removes the last element if including that element would cause the hierarchy to exceed 1024 characters. |
Mobile (Android & iOS)
The following events and properties become available after you install Heap on either Android or iOS. To get Heap for one or both of these platforms, see our Android Installation Guide and iOS Installation Guide.
Mobile User Properties
The following mobile user properties are only available for iOS or Android installations of Heap.
| Property | Definition |
|---|---|
| Initial Device | The device that the user accessed your site or app from during their very first session. |
Mobile Session Properties
The following session properties are only available for iOS or Android installations of Heap. On mobile, a session ends after 5 minutes of inactivity.
| Property | Definition |
|---|---|
| Device | The user's device. |
| Initial Device | The user's initial device. |
| Device Model | The model of the device, ex. Samsung Galaxy, etc. |
| Initial Device Model | The initial model of the device, ex. Samsung Galaxy, etc. |
| Device Platform | The version of the device, ex. iOS 14, Android 13, etc. |
| Initial Device Platform | The initial version of the device, ex. iOS 14, Android 13, etc. |
| Device Type | The type of device, ex. mobile, tablet, desktop, TV, watch, automotive, or unknown. |
| Initial Device Type | The initial type of device, ex. mobile, tablet, desktop, TV, watch, automotive, or unknown. |
| Carrier | The user's cell phone carrier. |
| Initial Carrier | The user's cell phone carrier name during their first session. |
| Vendor ID | The vendor ID of the device (opt-in only). Currently iOS only, coming soon to Android. |
| Initial Vendor ID | The initial vendor ID of the device (opt-in only). Currently iOS only, coming soon to Android. |
| Advertiser ID | The advertiser ID of the device (opt-in only). Currently iOS only, coming soon to Android. |
| Initial Advertiser ID | The initial advertiser ID of the device (opt-in only). Currently iOS only, coming soon to Android. |
| App Name | The current name of your mobile app, as determined by iOS CFBundleName or Android build configuration APPLICATION_ID . |
| App Version | The current version of your mobile app, as determined by iOS CFBundleShortVersionString or Android build configuration VERSION_CODE. |
| App Identifier | The identifier of the app, either a bundle identifier on iOS or a package or application ID on Android. |
Mobile Event Properties
The following event properties are only available for iOS or Android installations of Heap.
| Property | Definition |
|---|---|
| App Visibility State | The state of the event. e.g. Foregrounded or Backgrounded. |
| Hierarchy | The list of nested UI components from the most specific to the most general in relation to the event. |
Android
The following events and properties become available after you install Heap on Android. To get Heap for Android, see our Android Installation Guide.
Android Events
The following events are only available for Android installations of Heap.
| Event | Definition | Where It Comes From |
|---|---|---|
| Touch On | A tap or touch on a particular UI control. | View.OnClickListener.onClick() |
| View Screen | A screen view for Android. Behind the scenes, this is actually an Activity transition. | Application.ActivityLifecycleCallbacks.onActivityStarted() |
| Fragment Transition | Since some screens are comprised of exclusively Fragments, Fragment transition events are designed to capture screen views that aren’t covered strictly by an Activity transition. |
Fragment.onStart(), Fragment.onStop(), Fragment.onHiddenChanged()
|
| Edit Field | De-bounced edits of a form field. Text values are not captured, just the fact that the value was changed. | TextWatcher.onTextChanged() |
| App Install/Upgrade | An install or upgrade of an app. | Application package metadata |
| Change Events | Changes in the values of a variety of different components. Ex. switches, checkboxes, sliders, etc. | This depends on the change |
Android User Properties
| Property | Definition | Example | Event Types | Where It Comes From |
|---|---|---|---|---|
| Initial Android Advertiser ID | The Advertising ID is a user-resettable identifier and is appropriate for ads use cases. Assigned to the user during their very first session. | cdda802e-fb9c-47ad-0794d394c912 | All event types, as well as an initial user property |
AdvertisingIdClient from either in androidx.ads or the com.google.android.gms.ads package. |
Android Event Properties
The following event properties are only available for Android installations of Heap.
| Property | Definition | Example | Event Types | Where It Comes From |
|---|---|---|---|---|
| App Name | The name of the app that the event was fired from. | MyApp | All Events | Android app metadata |
| App Version | The version string of the app that the event was fired from. | 1.0.0 | All Events | Android app metadata |
| City | The city where the device is currently located. | Oakland | All Events | GeoIP lookup (MaxMind) |
| Country | The country where the device is currently located. | United States | All Events | GeoIP lookup (MaxMind) |
| Device | The name of the device that the app is installed on. | SM-G960U | All Events | Device metadata |
| Device Type | The type of device that the app is installed on. | Mobile | All Events | Device metadata |
| Activity | The class name of the Android Activity that's currently visible. | MoviesListingActivity | - Screenview (Activity Transition) - Fragment Transition - Touch - Page Transition |
Activity.getClass().getCanonicalName() |
| Full Activity | The fully-qualified class name of the Android Activity that's currently visible. | listing.MoviesListingActivity | - Screenview (Activity Transition) - Fragment Transition - Touch - Page Transition |
Activity.getClass().getName() |
| Android Advertiser ID | The Advertising ID is a user-resettable identifier and is appropriate for ads use cases. | cdda802e-fb9c-47ad-0794d394c912 | All event types, as well as an initial user property |
AdvertisingIdClient from either in androidx.ads or the com.google.android.gms.ads package. |
Android Advertiser ID
Android Advertiser ID is only captured when either the
com.google.android.gms.ads or the androidx.ads package is available to your app. If both these packages are missing, then the Android Advertiser ID will be omitted.| Android ID | A 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user, and device. | df19538d519e0ff5 | All event types, as well as an initial user property | Fetched from "secure system settings". |
| Platform | The name and version of the operating system that the device is running on. | Android 9 | All Events | Device metadata |
| Region | The region where the device is currently located. | California | All Events | GeoIP lookup (MaxMind) |
| Source | The source library that the event came from. Will always be “android” for autocaptured Android events. | android | All Events | Heap SDK |
| Added Fragments | A comma-separated list of Android Fragment classes that were added to the screen. | com.esoxjem.movieguide.details.MovieDetailsFragment,com.esoxjem.movieguide.listing.MoviesListingFragment | Fragment Transition | Fragment.class.getName() |
| Visible Fragments | A comma-separated list of Android Fragment classes that are currently visible on the screen. | com.esoxjem.movieguide.details.MovieDetailsFragment,com.esoxjem.movieguide.listing.MoviesListingFragment | - Fragment Transition - Touch - Page Transition |
Fragment.class.getName() |
| Removed Fragments | A comma-separated list of Android Fragment classes that were removed from the screen | com.esoxjem.movieguide.details.MovieDetailsFragment,com.esoxjem.movieguide.listing.MoviesListingFragment | Fragment Transition | Fragment.class.getName() |
| Full Target Resource ID | The fully-qualified resource ID associated with the UI control that was touched. | com.esoxjem.movieguide:id/movie_container | - Touch - Page Transition |
View.getId() |
| Target Class | The class name of the UI control that was touched. | android.widget.FrameLayout | - Touch - Page Transition |
View.getClass().getName() |
| Target Resource ID | A short resource ID associated with the UI control that was touched. | movie_container | - Touch - Page Transition |
View.getId() |
| Target Text | The text associated with the UI control that was touched. | Submit | Touch |
View.getText() for the associated view and its children/descendants |
| Content Description | The content description associated with the page elements that were interacted with. Typically used for adding additional metadata or contextual information. | Arbitrary text | All Events |
android:contentDescription in XML layouts, View.getContentDescription()
|
| Previous Version Name | The name of the previous version of the app installed. Only applies to upgrade events. | 1.0 | App Install/Upgrade | Application package metadata |
| Current Version Name | The name of the current version of the app installed. Applies to install or upgrade events. | 2.0 | App Install/Upgrade | Application package metadata |
| Is Upgrade | Whether or not this was an upgrade: true if the event indicated an upgrade, false if this was a first-time installation. | true | App Install/Upgrade | Application package metadata |
iOS
The following events and properties become available after you install Heap on iOS. To get Heap for iOS, see our iOS Installation Guide.
iOS Events
The following events are only available for iOS installations of Heap.
| Event | Definition | Where It Comes From |
|---|---|---|
| Touch | A tap or touch on a particular UI control. | Captured from any UIEvent fired from any UIView that includes UITouch objects. |
| View Screen | A screen view for iOS. | Captured from any UIViewController that gets a viewDidAppear or viewDidDisappearmessage. |
| Action Method | Function triggered when an interaction occurs on a particular UI control. | Captured from any component that fires an “action”, such as those configured through InterfaceBuilder or manually specified with a selector. These can often be a direct result of a Touch event, so they can be automatically combined into a single Heap event. |
| Edit field | De-bounced edits of a form field. Text values aren't captured, just the fact that the value was changed. | Captured from the UITextFieldTextDidEndEditingNotification sent through the NSNotificationCenter. |
| App Install/Upgrade | App install or upgrade. | At startup, the CFBundleShortVersionString is captured as the “version” and CFBundleVersion as the “build”. |
iOS User Properties
| Property | Definition | Example | Event Types | Where It Comes From |
|---|---|---|---|---|
| Initial iOS Vendor ID | An alphanumeric string that uniquely identifies a device to the app’s vendor. Assigned to the user during their very first session. | 4AA4DF6C-EAA1-4511-8A65-F8D07078F0A8 | All event types, as well as an initial user property | Apple provides the [UIDevice identifierForVendor] API to fetch this identifier. |
| Initial iOS Advertiser ID | An alphanumeric string unique to each device, used only for serving advertisements. Assigned to the user during their very first session. | EA7583CD-A667-48BC-B806-42ECB2B48606 | All event types, as well as an initial user property | Apple provides the [[ASIdentifierManager sharedManager] advertisingIdentifier] API to fetch this identifier. |
The iOS Advertiser ID is only captured when your app is linked with the AdSupport framework. If AdSupport is missing, the iOS Advertiser ID will be omitted.
iOS Event Properties
The following event properties are only available for iOS installations of Heap.
| Property | Definition | Example | Event Types | Where It Comes From |
|---|---|---|---|---|
| App Name | The name of the app that the event was fired from. | MyApp | All Events | iOS app metadata |
| App Version | The version string of the app that the event was fired from. | 1.0.0 | All Events | iOS app metadata |
| City | The city where the device is currently located. | Oakland | All Events | GeoIP lookup (MaxMind) |
| Country | The country where the device is currently located. | United States | All Events | GeoIP lookup (MaxMind) |
| Device | The name of the device that the app is installed on. | iPhone 6 | All Events | Device metadata |
| Device Type | The type of device that the app is installed on. | Mobile | All Events | Device metadata |
| iOS Advertiser ID | An alphanumeric string unique to each device, used only for serving advertisements. | EA7583CD-A667-48BC-B806-42ECB2B48606 | All event types, as well as an initial user property | Apple provides the [[ASIdentifierManager sharedManager] advertisingIdentifier] API to fetch this identifier. |
iOS Advertiser ID
The iOS Advertiser ID is only captured when your app is linked with the AdSupport framework. If AdSupport is missing, the iOS Advertiser ID will be omitted.
| iOS Vendor ID | An alphanumeric string that uniquely identifies a device to the app’s vendor. | 4AA4DF6C-EAA1-4511-8A65-F8D07078F0A8 | All event types, as well as an initial user property | Apple provides the UIDevice identifierForVendor API to fetch this identifier. |
| Platform | The name and version of the operating system that the device is running. | iOS 12.3 | All Events | Device metadata |
| Region | The region where the device is currently located. | California | All Events | GeoIP lookup (MaxMind) |
| Source | The source library that the event came from. Will always be “ios” for autocaptured iOS events. | ios | All Events | Heap SDK |
| View Controller | The class name of the View Controller that is currently visible. | MyAppViewController | - Screenview - Action Method - Touch - Edit field |
NSStringFromClass([UIViewController class]) |
| Title | The title of the View Controller that is currently visible. | My App | Screenview | [UIViewController title] |
| Target Accessibility Label | The accessibility label that is set for the control or active view controller. | Accessibility Label | - Screenview - Touch - Edit field |
[UIView accessibilityLabel] |
| Action Method | The name of the method that gets called when the control interaction occurs. | buttonPressed | - Action Method - Touch |
Captured from sendAction
|
| Target View Class | The class name of the UI control that was touched. | _UIButtonBarButton | - Action Method - Touch - Edit field |
NSStringFromClass([UIView class]) |
| Target View Name | The variable name of the target UIView that was interacted with. | tableView | - Action Method - Touch |
ivar_getName(IVar) |
| Target Text | The text associated with the UI control that was touched. | Submit | - Action Method - Touch |
[UIView text] |
| Previous Version Code | The version code of the previous version of the app installed. Only applies to upgrade events. | 1.0 | App Install/Upgrade | Application package metadata |
| Current Version Code | The version code of the current version of the app installed. Applies to install or upgrade events. | 2.0 | App Install/Upgrade | Application package metadata |
| Is Upgrade | Whether or not this was an upgrade: true if the event indicated an upgrade, false if this was a first-time installation. | true | App Install/Upgrade | Application package metadata |