Android Event Visualizer


Heap’s Event Visualizer for Android allows you to easily define Android events from within Heap. You can then use these events in your analysis to look for opportunities to optimize your user experience on Android.

Using the Android Event Visualizer

Pairing a Device or Emulator with the Android Event Visualizer

To use the Event Visualizer for Android, once it has been enabled for your app and environment, navigate to Define > Event Visualizer and click the ‘Android’ tab.

The Event Visualizer will automatically search for a nearby device to pair with, which can be either a physical Android device or an Android emulator.

To pair your device or emulator using the default pairing gesture, perform the following sequence within 15 seconds:

  1. Press the Volume Up button three times.
  2. Press the Volume Down button three times.
  3. Press the Volume Up button three times.
  4. Press the Volume Down button three times.

When your device is available for pairing, it will show up in the list:

Selecting a device will initiate the pairing flow, and Heap will randomly generate a four-digit pairing code, and push a notification to the device requesting confirmation that pairing is desired:

Once the pairing has been accepted, the Event Visualizer screen will provide a confirmation.

Using the Android Event Visualizer to Capture and Define Virtual Events

Once the Event Visualizer is paired to a device, actions will be captured by the Event Visualizer and displayed in the Heap web interface:

The events are displayed in two panes. On the left is the event screenshot, and on the right is the list of events and matching definitions (if the event is defined).

When an event is captured by Heap, the Event Visualizer will also capture a screenshot of the app at the time of the event. This is only captured while the Event Visualizer is paired, and it will not capture screenshots from live production users. If the event captured is a touch event, then the location of the gesture interaction will also be displayed as a red dot. Hovering over elements of the captured event list will switch between screenshots to make it easier to define the proper event.

Selecting one of the items in the event list will bring up the Event Definition sidebar, where you can define events. Events can be defined as is, using the pre-populated data, or additional filters and criteria can be specified to adjust the event definition.

Android Developers: Defining an Alternate Method for Initiating Pairing

The Android Event Visualizer utilizes a pairing flow to ensure that events are only captured from an intended Android device or emulator. To enable this, the Android SDK will introduce two new methods to the client library: Heap.startEVPairing() and Heap.stopEVPairing().

The Heap.startEVPairing() method should generally be activated via a button in a debug menu or by implementing a specialized gesture that will trigger the method call. Once startEVPairing() has been called, you will be able see the device or emulator in a list of possible pairings.

It is important to note that this function can be called as the app is starting up in Application.onCreate(), though this is not recommended for production builds. This is because it could result in:

  1. A large number of devices becoming pairing candidates.
  2. If the pairing is cut off by clicking the disconnect button within the Heap web app, it will not be possible to repair with the app until it is forcefully closed and re-opened.

Heap.stopEVPairing() is a generally optional call that can be made if you want to have a way to explicitly disable pairing from the app, but is not strictly necessary, as the connection will be severed after a successful pairing and subsequent Heap web app-initiated disconnection.

Best Practices for Defining Android Events

Autocaptured data is, by its very nature, application-level information that is captured from a mobile or web app. As a result, it can sometimes be tricky to interpret if you don’t understand the technical details of how web and mobile apps are built. The Android Event Visualizer attempts to make this easier by providing screenshots and human-readable text descriptions of what is occurring. The best practices section of this guide aims to demystify details about the actual data, which is helpful in understanding which events to tag.

Defining Screenview Events

Under the hood, Android developers may implement screens in an Android app in a variety of different ways. In Heap, the Android View screen event is tied to an Activity transition, which is the most common way of representing a screen. Another common way of implementing screens is using Fragments, which are represented as Fragment transition events in Heap. In some Android apps, a single MainActivity is used, and all screens may be implemented as Fragment transitions. In others, only Activities or used. Most commonly, apps use a mix of both Activities and Fragments, so it’s best to leverage the screenshots to identify the event you care most about.

A note on Fragments: while Activity transitions almost always indicate a new screenview, Fragment transitions do not always line up with a screen change. In the example app shown in this doc, each movie card is represented with a Fragment, and as a user scrolls through the list (causing more cards to be loaded onto the screen), the Fragment transitions will trigger in Heap. It is up to you to decide how to interpret these sorts of Fragment transitions as they relate to your app.

Sometimes, a screenview event will trigger more than one autocaptured event. For example, when tapping on a particular movie listing, three visual changes occur after the tap:

  1. First fragment transition: MovieDetailsFragment is added
  2. Activity transition: MovieDetailsActivity is loaded
  3. Second fragment transition: MoviesListingFragment is removed

In the context of this app, the removal of MoviesListingFragment indicates the previous screen being unloaded, followed by an Activity transition, which is the new screen loading; last, the addition of the MovieDetailsFragment loads a final component of the screen. Since the Fragment only represents a portion of the screen, and there is a clear Activity transition, it makes sense to use the MovieDetailsActivity transition to represent a Screenview on the Movie Details Screen.

Common properties for defining screenviews with Activity transitions:

  • Activity or Full Activity

Common properties for defining screenviews with Fragment transitions:

  • Added Fragments
  • Activity or Full Activity

Defining ViewPager Events

ViewPagers are Android UI elements that are commonly used for swipeable screens, such as onboarding tutorials. They may also be used as navigation elements, allowing users to either tap a button or swipe to switch between a set of pages or screens. Heap captures these events as Page transition events. Since the ViewPagers may have either programmatic transitions (typically triggered by a button tap) or swiped transitions, the event has a property called View Pager Swiped, which indicates whether the transition was programmatic (the value will be false) or initiated by a swipe gesture (the value will be true).

ViewPagers have a few ways of indicating the details of the transition: using the from and to page titles, which are typically human-readable descriptions; using class names, which are useful if they differ from page to page; or using indexes, which are numeric indicators of the order of the pages in the ViewPager (the indexes are 0-indexed). By defining events with filters on from or to details, it is possible to specify events that will capture any page transition to a particular page, or from a particular page (or being entirely specific about both the from and to pages).

Common properties for defining Page transitions:

  • Transitioned-to Page Title
  • Transitioned-from Page Title
  • View Pager Swiped

Defining Touch Events

In Android apps, touch events occur on UI elements that are labeled with resource IDs. These resource IDs can typically be used to uniquely identify a UI element on a screen, and can be used effectively for event definition. If the resource ID is reused on multiple screens, the tagged event can be made more specific by also including a filter on the Activity or set of Visible Fragments, which can be used to identify the particular screen that the touch occurred on. If a particular resource ID is reused on the same screen, it will typically be necessary to use other properties like Target Text (for example, a button with the label “Sign In” will have that text captured as Target Text).

Common properties for defining touch events:

  • Hierarchy
  • Target Resource ID (as a filter)
  • Target Text
  • Activity
  • Visible Fragments

Touch & Edit Field Event Definition Differences for Android 1.4.0+

In Android SDK versions 1.4.0 and up, we capture and use the view hierarchy to define touch and edit field events. in Android SDK versions below 1.4.0, touch and edit field events are defined via the target resource ID.

If your app is running on an Android SDK version that is older than 1.4.0, the data that Heap receives will not contain the view hierarchy. To define events for these apps, leave the view hierarchy blank, and use additional filters to narrow your criteria for defining your event. You can also use a combo event to tie older and newer event versions together.

Defining Edit Field Events

The Heap Android SDK will automatically capture modifications to form fields using an edit field event. The actual text that is entered will not be captured, as form fields will often contain PII.

Common properties for defining field edit events:

  • Hierarchy
  • Target Resource ID (as a filter)
  • Activity

Defining App Install/Upgrade Events

Heap will capture app install and upgrade events, and indicate whether the event was a first-time install or upgrade, as well as the current and previous (if applicable) versions of the app that are installed. It is important to note that if a user installs or upgrades the app, but never opens it, no install or upgrade event will be captured. In the event of a user upgrading multiple times between app opens, there will only be one upgrade event captured at the time of app open.

Since app installs and upgrades are triggered upon app open, they will generally not appear in the Event Visualizer. It is recommended to use the Live View or Users View to define these events.

Common properties for defining app install/upgrade events:

  • Is upgrade
  • Current version name

Enriching Autocaptured Data

On occasion, autocaptured data does not contain enough specific information to adequately define an event. A common place where this might happen is on a settings screen, where toggle switches may be used to turn on or off certain options. A settings screen like this might use the same target resource ID for all of the toggle switches, which makes it difficult to differentiate one switch from another. Additionally, since toggle switches don’t have title or label text associated with them like a button might, it becomes necessary to enrich the autocaptured data with additional contextual information. Heap provides a number of ways to perform this enrichment.

Content Descriptions

In Android apps, content descriptions can be used to add additional contextual information for touchable UI elements that don’t have other distinctive characteristics that are usable in an event definition. If there is a touch or other interaction on a UI element with a content description set, then the autocaptured event will include a Content Description property that can be used in the event definition filters.

Adding Event Properties

Sometimes, it may be desirable to add additional properties to any interaction on a particular screen. For example, you might want to add a product price and name to an autocaptured event for when a user taps on the Add to Cart button, or perhaps there is a product ID that should be associated with all events on a product screen, but that product ID doesn’t appear in the screen UI.

For situations like this, the addEventProperties() API enables developers to specify properties that should be captured with any interaction on a screen. Properties added with this API method will be captured with all captured events until clearEventProperties() or removeEventProperty() is called.

NOTE: addEventProperties() cannot effectively be used for situations where different interactions on a screen should receive different sets of properties. A common example might be a screen that displays a list, and a tap on a list element needs to be enriched with different values depending on which element is tapped.

Instrumenting Events

For situations where addEventProperties() API calls and Content Descriptions are not enough, Heap provides the ability to precisely instrument events with track() calls. Events instrumented with track() can be used in Combo Events, and can be used alongside autocaptured events in Heap’s analysis modules.


Pairing gesture is not being recognized

Due to the structure of certain apps, in some apps, the pairing gesture may not be consistently recognized by the Heap SDK. If you're having trouble getting the pairing gesture to work properly, it is recommended to have your app development team utilize our startEVPairing API to explicitly begin the pairing process. It is important that this API only be called in debug builds or via a hidden/debug gesture or menu button to avoid accidentally pairing with customer devices.

Updated a day ago

Android Event Visualizer

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.