Skip to content
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
Home Getting Started How Heap Works Autocaptured Data
Session Replay Getting Started Administration Data Management Definitions Charts Analysis Examples Heap Plays Integrations Heap Connect Data Privacy

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

Autocaptured Data

In this article you'll learn:

  • What events and properties Heap automatically captures in web, iOS, and Android
  • Caveats for certain event and properties (listed directly above those definitions)

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 an input, textarea, or select element (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.

EventDefinitionWhere it appears
SessionA session by a user.In the Graph, Users, Retention, and Influence analysis module definition drop-downs.
PageviewA 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:

PropertyDefinition
User IDA randomly generated user ID that is used to identify a user in Heap.
Initial ContinentThe continent that the user was identified as being in during the first session.
Date First SeenThe timestamp of when the user was first seen by Heap.
Initial LocationThe initial city, region, and country the user was identified as being in during the very first session.
Initial CityThe user’s city as determined by their IP address during their very first session.
Initial CountryThe user’s country as determined by their IP address during their very first session.
Initial RegionThe 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.

PropertyDefinition
EmailThe user’s email address. If you configure your Heap implementation to use the addUserProperties API, this is where it will appear.
HandleThe 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.
IdentityIf 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:

PropertyDefinition
Session IDA randomly generated ID number.
User IDThe ID of the associated user.
TimeThe timestamp of when the session began.
PlatformThe user’s operating system.
Device TypeThe device type, either Mobile, Tablet or Desktop.
CountryThe user’s country, based on their geolocation data.
RegionThe user’s region, based on their geolocation data.
CityThe user’s city, based on their geolocation data.
IP AddressThe IP address for the user’s session that we use to capture their geolocation data.
SourceThis 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:

PropertyDefinition
TypeThis can be any one of the following: view page, click, submit, change, with push state events registered as view page events.
TimeThe time when the event happened.
User IDThe ID of the associated user.
Session IDThe ID of the associated session.
Target TextThe text of the event target.
Event IDThe 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.

PropertyDefinition
Initial Landing PageThe 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 ReferrerThe 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 CampaignThese 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 TypeThe browser of the user during their very first session.
Initial BrowserThe browser the user came in on during their very first session.
Initial Device TypeThe type of device the user accessed your site or app from during their very first session.
Initial PlatformThe operating system used by the user during their very first session.
Initial IP AddressThe 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.

PropertyDefinition
ReferrerThe 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 ReferrerThe same as the referrer, though this contains the protocol, port, and path, if they exist.
Landing PageThe 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.
BrowserThe user’s browser.
UTM Source, UTM Medium, UTM Term, UTM Content, UTM CampaignThese 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.

PropertyDefinition
Target TagThe tag name of the event target’s DOM element, e.g. INPUT, DIV, or A.
Target IDThe ID of the event target’s DOM element, e.g. #login.
Target ClassThe class name of the event target’s DOM element, e.g. .primary-btn.
HrefThe href property of link. (for clicks on anchor tags).
Previous PageThe previous page visited in this session.
DomainThe current domain, including the subdomain, e.g. blog.heap.io.
HashThe part of the current URL following the hash sign, e.g. #install for heapanalytics.com/docs#install.
PathThe part of the current URL following your domain, e.g. /docs for heapanalytics.com/docs.
QueryThe query params of the page’s current URL, e.g. ?utm_id=1234 for heapanalytics.com?utm_id=1234.
TitleThe 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.

PropertyDefinition
Initial DeviceThe 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.

PropertyDefinition
DeviceThe user’s device.
CarrierThe user’s cell phone carrier.
Initial CarrierThe user’s cell phone carrier name during their first session.
App NameThe current name of your mobile app, as determined by iOS CFBundleName or Android build configuration APPLICATION_ID .
App VersionThe 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.

PropertyDefinition
Target View ClassThe underlying class name of an iOS action’s target, e.g. UITableCellView, or an Android android:onClick XML layout attribute.
Action MethodThe name of the action method triggered by this event, e.g. loginButtonWasPressed.
App Visibility StateThe 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.

EventDefinitionWhere It Comes From
Touch OnA tap or touch on a particular UI control.View.OnClickListener.onClick()
Activity methods targeted by android:onClick attributes in layout XML
View ScreenA screen view for Android. Behind the scenes, this is actually an Activity transition.Application.ActivityLifecycleCallbacks.onActivityStarted()
Page TransitionCaptures changes to a ViewPager control. Typically, these are used for onboarding flows, or for swipeable screens.ViewPager.OnPageChangeListener.onPageSelected()
Fragment TransitionSince 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 FieldDe-bounced edits of a form field. Text values are not captured, just the fact that the value was changed.TextWatcher.onTextChanged()
App Install/UpgradeAn install or upgrade of an app.Application package metadata

Android User Properties

PropertyDefinitionExampleEvent TypesWhere It Comes From
Initial Android IDA 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.df19538d519e0ff5All event types, as well as an initial user propertyFetched from “secure system settings”.
Initial Android Advertiser IDThe 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-0794d394c912All event types, as well as an initial user propertyAdvertisingIdClient 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.

PropertyDefinitionExampleEvent TypesWhere It Comes From
App NameThe name of the app that the event was fired from.MyAppAll EventsAndroid app metadata
App VersionThe version string of the app that the event was fired from.1.0.0All EventsAndroid app metadata
CityThe city where the device is currently located.OaklandAll EventsGeoIP lookup (MaxMind)
CountryThe country where the device is currently located.United StatesAll EventsGeoIP lookup (MaxMind)
DeviceThe name of the device that the app is installed on.SM-G960UAll EventsDevice metadata
Device TypeThe type of device that the app is installed on.MobileAll EventsDevice metadata
ActivityThe class name of the Android Activity that is currently visible.MoviesListingActivity– Screenview (Activity Transition)
– Fragment Transition
– Touch
– Page Transition
Activity.getClass().getCanonicalName()
Full ActivityThe 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 IDThe Advertising ID is a user-resettable identifier and is appropriate for ads use cases.cdda802e-fb9c-47ad-0794d394c912All event types, as well as an initial user propertyAdvertisingIdClient 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 IDA 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user, and device.df19538d519e0ff5All event types, as well as an initial user propertyFetched 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 AddressThe current IP address of the device.192.0.0.1All Events
Request metadata
PlatformThe name and version of the operating system that the device is running on.Android 9All EventsDevice metadata
RegionThe region where the device is currently located.CaliforniaAll EventsGeoIP lookup (MaxMind)
SourceThe source library that the event came from. Will always be “android” for autocaptured Android events.androidAll EventsHeap SDK
Added FragmentsA comma-separated list of Android Fragment classes that were added to the screen.com.esoxjem.movieguide.details.MovieDetailsFragment,com.esoxjem.movieguide.listing.MoviesListingFragmentFragment TransitionFragment.class.getName()
Visible FragmentsA 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 FragmentsA comma-separated list of Android Fragment classes that were removed from the screencom.esoxjem.movieguide.details.MovieDetailsFragment,com.esoxjem.movieguide.listing.MoviesListingFragmentFragment TransitionFragment.class.getName()
Full Target Resource IDThe fully-qualified resource ID associated with the UI control that was touched.com.esoxjem.movieguide:id/movie_container– Touch
– Page Transition
View.getId()
Target ClassThe class name of the UI control that was touched.android.widget.FrameLayout– Touch
– Page Transition
View.getClass().getName()
Target Resource IDA short resource ID associated with the UI control that was touched.movie_container– Touch
– Page Transition
View.getId()
Target TextThe text associated with the UI control that was touched.SubmitTouchView.getText() for the associated view and its children/descendants
Transitioned-from Class NameThe class of the beginning page during the page transition.android.widget.RelativeLayoutPage TransitionPageAdapter.getClass().getName()
Transitioned-to Class NameThe class of the ending page during the page transition.android.widget.RelativeLayoutPage TransitionPageAdapter.getClass().getName()
Transitioned-from Page TitleThe human-readable title of the beginning page during the page transition.How to Get StartedPage TransitionPageAdapter.getPageTitle()
Transitioned-to Page TitleThe human-readable title of the ending page during the page transition.Now You’re Ready To Go!Page TransitionPageAdapter.getPageTitle()
View Pager SwipedWhether 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.truePage TransitionCaptured from ViewPager.onPageScrollStateChanged() – if scroll state is set to SCROLL_STATE_DRAGGING, this property is set to true
Content DescriptionThe content description associated with the UI element that received an interaction. Typically used for adding additional metadata or contextual information.Arbitrary textAll Eventsandroid:contentDescription in XML layouts, View.getContentDescription()
Previous Version NameThe name of the previous version of the app installed. Only applies to upgrade events.1.0App Install/UpgradeApplication package metadata
Previous Build TypeThe type of build that was previously installed. Only applies to upgrade events.debugApp Install/UpgradeApplication package metadata
Current Version NameThe name of the current version of the app installed. Applies to install or upgrade events.2.0 App Install/UpgradeApplication package metadata
Current Build TypeThe type of build that is currently installed. Applies to install or upgrade events.release App Install/UpgradeApplication package metadata
Is UpgradeWhether or not this was an upgrade: true if the event indicated an upgrade, false if this was a first-time installation.true App Install/UpgradeApplication 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.

EventDefinitionWhere It Comes From
TouchA tap or touch on a particular UI control.Captured from any UIEvent fired from any UIView that includes UITouch objects.
View ScreenA screen view for iOS.Captured from any UIViewController that gets a viewDidAppear or viewDidDisappearmessage.
Action MethodFunction triggered when an interaction occurs on a particular UI controlCaptured 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 fieldDe-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 RecognizersApp-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/UpgradeInstall or upgrade of an appAt startup, the CFBundleShortVersionString is captured as the “version” and CFBundleVersion as the “build”.

iOS User Properties

PropertyDefinitionExampleEvent TypesWhere It Comes From
Initial iOS Vendor IDAn 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-F8D07078F0A8All event types, as well as an initial user propertyApple provides the [UIDevice identifierForVendor] API to fetch this identifier.
Initial iOS Advertiser IDAn alphanumeric string unique to each device, used only for serving advertisements. Assigned to the user during their very first session.EA7583CD-A667-48BC-B806-42ECB2B48606All event types, as well as an initial user propertyApple 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.

PropertyDefinitionExampleEvent TypesWhere It Comes From
App NameThe name of the app that the event was fired from.MyAppAll EventsiOS app metadata
App VersionThe version string of the app that the event was fired from.1.0.0All Events iOS app metadata
CityThe city where the device is currently located.OaklandAll EventsGeoIP lookup (MaxMind)
CountryThe country where the device is currently located.United StatesAll EventsGeoIP lookup (MaxMind)
DeviceThe name of the device that the app is installed on.iPhone 6 All EventsDevice metadata
Device TypeThe type of device that the app is installed on.MobileAll EventsDevice metadata
iOS Advertiser IDAn alphanumeric string unique to each device, used only for serving advertisements.EA7583CD-A667-48BC-B806-42ECB2B48606All event types, as well as an initial user propertyApple 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 IDAn alphanumeric string that uniquely identifies a device to the app’s vendor.4AA4DF6C-EAA1-4511-8A65-F8D07078F0A8All event types, as well as an initial user propertyApple provides the UIDevice identifierForVendor API to fetch this identifier.
IP AddressThe current IP address of the device.192.0.0.1All EventsRequest metadata
PlatformThe name and version of the operating system that the device is running. iOS 12.3All EventsDevice metadata
RegionThe region where the device is currently located.CaliforniaAll EventsGeoIP lookup (MaxMind)
SourceThe source library that the event came from. Will always be “ios” for autocaptured iOS events.iosAll EventsHeap SDK
View ControllerThe class name of the View Controller that is currently visible.MyAppViewController– Screenview
– Action Method
– Touch
– Edit field
NSStringFromClass([UIViewController class])
TitleThe title of the View Controller that is currently visible.My AppScreenview[UIViewController title]
Target Accessibility LabelThe accessibility label that is set for the control or active view controller.Accessibility Label– Screenview
– Touch
– Edit field
[UIView accessibilityLabel]
Accessibility IdentifierThe accessibility ID that is set for the control or active view controller.accessibilityId– Screenview
– Touch
– Edit field
[(id)UIView accessibilityIdentifier]
Action MethodThe name of the method that gets called when the control interaction occurs.buttonPressed– Action Method
– Touch
Captured from sendAction
Target View ClassThe class name of the UI control that was touched._UIButtonBarButton– Action Method
– Touch
– Edit field
NSStringFromClass([UIView class])
Target View NameThe variable name of the target UIView that was interacted with.tableView– Action Method
– Touch
ivar_getName(IVar)
Target TextThe text associated with the UI control that was touched.Submit– Action Method
– Touch
[UIView text]
Previous Version CodeThe version code of the previous version of the app installed. Only applies to upgrade events.1.0App Install/UpgradeApplication package metadata
Previous Build TypeThe type of build that was previously installed. Only applies to upgrade events.debugApp Install/UpgradeApplication package metadata
Current Version CodeThe version code of the current version of the app installed. Applies to install or upgrade events.2.0App Install/UpgradeApplication package metadata
Current Build TypeThe type of build that is currently installed. Applies to install or upgrade events.releaseApp Install/UpgradeApplication package metadata
Is UpgradeWhether or not this was an upgrade: true if the event indicated an upgrade, false if this was a first-time installation.trueApp Install/UpgradeApplication package metadata

Was this article helpful?

Yes No

Thank you for your feedback!

Last updated December 22, 2022.

autocaptureautocapture Androidautocapture iOSautocapture mobileautocapture webautocaptured eventsautocaptured propertiesautomatically captured eventsautomatically captured properties
  • Blog
  • Partners
  • Legal
  • Security
  • Terms
  • About
  • Careers
  • Privacy
  • Contact Us

© 2023 Heap, Inc.