Overview

Heap’s visual labeling for Android allows you to easily label 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 Android visual labeling

Pairing a Device or Emulator with Android visual labeling

To use visual labeling for Android, once it has been enabled for your app and environment, navigate to the visual labeling page and click the ‘Android’ tab.

The visual labeling interface 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 visual labeling screen will provide a confirmation.

Using Android visual labeling to Capture and Label Virtual Events

Once visual labeling is paired to a device, actions will be captured by visual labeling 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 events (if the event exists).

When an event is captured by Heap, visual labeling will also capture a screenshot of the app at the time of the event. This is only captured while visual labeling 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 label the proper event.

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

Android Developers: Alternate Method for Initiating Pairing

Android visual labeling 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 Labeling 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. Android visual labeling 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.

Labeling 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 notetaking app example app shown in this doc, each note is represented with a Fragment, and as a user scrolls through the list (causing more note 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 main item, these visual changes occur after the tap:

Common properties for labeling screenviews with Activity transitions:

• Activity or Full Activity

Common properties for labeling screenviews with Fragment transitions:

• Added Fragments
• Activity or Full Activity

Labeling 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 labeling 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 labeling Page transitions:

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

Labeling 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 events. 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 labeling touch events:

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

Labeling 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 labeling field edit events:

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

Labeling 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 visual labeling. It is recommended to use the Live View or Users View to label these events.

Common properties for labeling app install/upgrade events:

• Is upgrade
• Current version name

Enriching Autocaptured Data

On occasion, autocaptured data does not contain enough specific information to adequately label 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. 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 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.

Troubleshooting

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.

Seeing heap-ignored elements in visual labeling screenshots

When using visual labeling, screenshots are taken to help label events in the UI. These screenshots are not stored by Heap, and Heap will only capture such screenshots when visual labeling is actively in use. Heap-ignored elements within a view are not obscured in these screenshots, but any interactions with the ignored element in the view will not trigger events in Heap.