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 (organized into user, session, and event 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.
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 are not modifiable. If you’d like to redefine an event or property, you can make a copy of it, update and rename the copy as needed, then save it as a new event or property.
For information on what session replay captures, see What does session replay capture?
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 will not have any definitions listed. However, the following two events can be accessed via the analysis module definition drop-downs (listed 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 Graph, Users, Retention, and Influence analysis module definition drop-downs. |
| Pageview | A pageview by a user. | In all of the analysis modules definition drop-downs. |
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 query 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 is 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 configure your Heap implementation to use the addUserProperties API, this is where it will appear. | |
| Handle | The user’s handle (also known as a username). If you configure your Heap implementation to use 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
A session is a period of activity from a single user in your app or website. One session can include many pageviews or events. On the web, a session ends after 30 minutes of pageview inactivity from the user. On mobile, a session ends after 5 minutes of inactivity.
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 cannot 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 modify the query 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. |
| IP Address | The IP address for the user’s session that we use to capture their geolocation data. |
| Source | This indicates which Heap snippet or SDK the data was captured by: either Web, iOS, or Android. |
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. |
| Initial IP Address | The IP address identified for the user during their very first session. |
Web Session Properties
The following session properties are only available for web installations of Heap. On the web, a session ends after 30 minutes of pageview inactivity from the user.
| 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 an end-user 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. /docs for heapanalytics.com/docs. |
| 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. |
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. |
| Carrier | The user’s cell phone carrier. |
| Initial Carrier | The user’s cell phone carrier name during their first session. |
| 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. |
Mobile Event Properties
The following event properties are only available for iOS or Android installations of Heap.
| Property | Definition |
|---|---|
| Target View Class | The underlying class name of an iOS action’s target, e.g. UITableCellView, or an Android android:onClick XML layout attribute. |
| Action Method | The name of the action method triggered by this event, e.g. loginButtonWasPressed. |
| App Visibility State | The state of the event. e.g. Foregrounded or Backgrounded. |
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.
View Hierarchy Property
The view hierarchy is another property that is autocaptured for Android. However, because it cannot be used in analysis, it is not listed on the properties page in Heap.
For apps running the Heap Android SDK versions 1.4.0 and above, the view hierarchy is used to define touch and edit field events.
| Event | Definition | Where It Comes From |
|---|---|---|
| Touch On | A tap or touch on a particular UI control. | View.OnClickListener.onClick()Activity methods targeted by android:onClick attributes in layout XML |
| View Screen | A screen view for Android. Behind the scenes, this is actually an Activity transition. | Application.ActivityLifecycleCallbacks.onActivityStarted() |
| Page Transition | Captures changes to a ViewPager control. Typically, these are used for onboarding flows, or for swipeable screens. | ViewPager.OnPageChangeListener.onPageSelected() |
| 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 |
Android User Properties
| Property | Definition | Example | Event Types | Where It Comes From |
|---|---|---|---|---|
| Initial Android ID | A 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user, and device. Assigned to the user during their very first session. | df19538d519e0ff5 | All event types, as well as an initial user property | Fetched from “secure system settings”. |
| 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. |
On API levels <26, the Android ID is not user-resettable, and so defaults to opt-in. This identifier on API levels >=26 (as well as the other three identifiers) are opt-out by default.
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 is 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 is current 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”. |
Android ID
On API levels <26, the Android ID is not user-resettable, and so this defaults to opt-in. This identifier on API levels >=26 (as well as the other three identifiers) is opt-out by default.
| IP Address | The current IP address of the device. | 192.0.0.1 | All Events | Request metadata |
| 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 |
| Transitioned-from Class Name | The class of the beginning page during the page transition. | android.widget.RelativeLayout | Page Transition | PageAdapter.getClass().getName() |
| Transitioned-to Class Name | The class of the ending page during the page transition. | android.widget.RelativeLayout | Page Transition | PageAdapter.getClass().getName() |
| Transitioned-from Page Title | The human-readable title of the beginning page during the page transition. | How to Get Started | Page Transition | PageAdapter.getPageTitle() |
| Transitioned-to Page Title | The human-readable title of the ending page during the page transition. | Now You’re Ready To Go! | Page Transition | PageAdapter.getPageTitle() |
| View Pager Swiped | Whether or not the transition was triggered by a swipe gesture: true if initiated by a swipe, false if not. Often, this will be false if users switch pages by tapping a tab button to switch pages. | true | Page Transition | Captured from ViewPager.onPageScrollStateChanged() – if scroll state is set to SCROLL_STATE_DRAGGING, this property is set to true |
| Content Description | The content description associated with the UI element that received an interaction. 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 |
| Previous Build Type | The type of build that was previously installed. Only applies to upgrade events. | debug | 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 |
| Current Build Type | The type of build that is currently installed. Applies to install or upgrade events. | release | 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 are not captured, just the fact that the value was changed. | Captured from the UITextFieldTextDidEndEditingNotification sent through the NSNotificationCenter. |
| Gesture Recognizers | App-specific actions implemented by particular gesture recognizers e.g. Pan On, longPress On, etc. | Captured from Key-Value Observation (KVO) on the state of the UIGestureRecognizer class. When the state transitions to UIGestureRecognizerStateEnded, an event is recorded. |
| App Install/Upgrade | Install or upgrade of an app | 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.
View Hierarchy Property
The view hierarchy is another property that is autocaptured for iOS. However, because it cannot be used in analysis, it is not listed on the properties page in Heap.
For apps running the Heap iOS SDK versions 6.5.0 and above, the view hierarchy is used to define touch and edit field events.
| 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. |
| IP Address | The current IP address of the device. | 192.0.0.1 | All Events | Request metadata |
| 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] |
| Accessibility Identifier | The accessibility ID that is set for the control or active view controller. | accessibilityId | – Screenview – Touch – Edit field | [(id)UIView accessibilityIdentifier] |
| 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 |
| Previous Build Type | The type of build that was previously installed. Only applies to upgrade events. | debug | 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 |
| Current Build Type | The type of build that is currently installed. Applies to install or upgrade events. | release | 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 |