Overview

You can use visual labeling for iOS allows you to easily label iOS events from within Heap. You can then use these events in your analysis to look for opportunities to optimize your user experience on iOS.

Pairing a Device or Simulator

There are two options for pairing your device with iOS visual labeling. We strongly recommend using option 1. The exception is if you are developing the app while pairing, in which case we recommend option 2. 

Option 1 (Recommended): Via QR Code

Navigate to the visual labeling page and click the iOS tab. Open your device to scan the QR code displayed on this page. 

Once scanned, your device will enter pairing mode, and you will have to confirm the pairing on your device. Once confirmed, Heap will display events that can be labeled. Your device should immediately become visible in the visual labeling device list, and a green indicator at the top of the Heap app will show that pairing is active.

Option 2: Via Gesture

This option is only provided as a fallback in case you can’t use the QR code method.

To use the pairing gesture method, navigate to the visual labeling page and click the iOS tab.

The visual labeling interface will automatically search for a nearby device to pair with, which can be either a physical iOS device or an iOS simulator.

To pair your physical device using the default pairing gesture, hold four fingers down on the screen for five seconds. If the locations of your fingers trigger other gestures or actions (such as button presses), the pairing gesture may not get triggered.

To pair a simulator using the default pairing gesture, use the Hardware -> Shake Gesture option from the simulator menu.

When your device is available for pairing, it will show up in the list for you to select. Selecting a device will initiate the pairing flow. 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 confirm:

Using iOS visual labeling to Capture & Label Virtual Events

Once visual labeling is paired to a device, actions will be captured in 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 criteria.

iOS Developers: Enabling visual labeling Pairing

iOS visual labeling uses a pairing flow to make sure that events are only captured from an intended iOS device or simulator. To enable this, the iOS 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 [Heap startEVPairing] this ​has been called, you’ll be able to see the device or emulator in a list of possible pairings.

[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. It’s not strictly necessary, as the connection will be severed after a successful pairing and subsequent Heap web app-initiated disconnection.

If desired, the default gesture used for pairing can be disabled with [Heap disableVisualizerPairingGesture].

Best Practices for Labeling iOS Events

Autocaptured data is, by its very nature, application-level information that’s 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. iOS 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, iOS screens are almost always associated with a View Controller object. In Heap, the iOS ‘View screen’ event is tied to a ViewController transition. When a new screen loads in the app, Heap will autocapture an event that provides the name of the ViewController, though that event can be re-labeled with a name that fits into your event taxonomy.

Common properties for labeling screenviews:

• View Controller

Labeling Touch Events

In iOS apps, touch events occur on UI elements called UIViews. Depending on the structure of the app’s code, touch events may capture different pieces of data. The Target View Name is typically the most specific piece of information for a touch event, as this relates back to the name that the UIView has in the app’s code, and will generally uniquely identify the UI element. Sometimes Heap isn’t able to capture the Target View Name. In these situations, oftentimes a combination of other properties can be used to label the event.

The Target View Class, if not a generic name like UIButton or UIView, can be used to inform the event, and Target Text or an Accessibility Label can be used to more specifically label the interaction. If a UI element appears on multiple screens, the tagged event can be made more specific by also including a filter on the View Controller as well, to specifically identify the screen that the interaction occurred on.

Common properties for labeling touch events:

• Hierarchy
• Target View Name
• Target Text
• Target View Class
• View Controller
• Target accessibilityLabel

Labeling Action Method Events

It’s common to see interactions in iOS apps that produce more than one event. Oftentimes, a touch will also produce an Action Method event. At a technical level, Action Methods are important events that relate to the Target-Action app design pattern.

iOS developers use action methods to determine what the app should do behind the scenes when a user interacts with a UI element, like tapping a button or toggling a switch. The name of that method can sometimes be very descriptive (pushPurchase), but is also sometimes very generic (buttonDown). As a result, depending on how an app is built, Action Methods are sometimes very useful for labeling events, and sometimes can be ignored.

In cases like this, filtering for the Action Method property in addition to the Target View Class property will allow you to uniquely identify the specific interaction you want to capture.

Common properties for labeling action methods:

• Action Method
• Target View Class
• View Controller

Labeling Field Edit Events

The Heap iOS SDK will automatically capture modifications to form fields using a ‘Field edit’ event. Labeling an event for a particular form field is often very similar to labeling a touch event. The actual text that’s entered will not be captured, as form fields often contain PII.

Common properties for labeling field edit events:

• Target View Name
• Target Text
• Target View Class
• View Controller
• Target accessibilityLabel

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 instances of opening the app, there will only be one upgrade event captured at the time that they opened the app.

Since app installs and upgrades are triggered when the app is opened, they’ll generally not appear in visual labeling. It’s recommended to use live data feed or the labeled events page to label these events.

Common properties for labeling app install/upgrade events:

• Is Upgrade
• Current Version Code

Enriching Autocaptured Data

On occasion, autocaptured data won’t contain enough specific information to adequately label an event. A commonplace 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 View Class for all of the toggle switches, which makes it difficult to differentiate one switch from another. Additionally, since toggle switches don’t have a 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.

Accessibility Labels

In iOS apps, accessibility labels 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 label. If there is a touch or other interaction on a UI element with a content description set, then the autocaptured event will include a Target accessibilityLabel` 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 [Heap addEventProperties:@{@"PropName":@"Value"}] API enables developers to specify which properties should be captured with any interaction on a screen. Properties added via this API method will be captured with all captured events until [Heap clearEventProperties] or [Heap removeEventProperty:@"Property"] is called.

NOTE: [Heap 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 [Heap addEventProperties] API calls and Target accessibilityLabels are not enough, Heap provides the ability to precisely instrument events with [Heap track] calls. Events instrumented with [Heap track] can be used in Combo Events, and can be used alongside autocaptured events in Heap’s analysis modules.

Troubleshooting

(Option 1 only) QR code scan isn’t working

If you aren’t being prompted to launch your app after the QR code has been scanned, please review the installation instructions and verify that the visual labeling pairing trigger has been installed for your environment.

(Option 1 only) Device not showing on the list

If you are being prompted to launch your app but your device isn’t showing up in the list, verify that your internet connection is active and that you aren’t connected to a VPN.

(Option 2 only) 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. The gesture is sometimes easier to activate on certain screens than others. If there is a screen that has an area without UI elements that can be interacted with, those are often the easiest screens to use for pairing. If placing your fingers down on the screen triggers an event captured by Heap, it is unlikely that the pairing gesture will be recognized with that finger placement.

If you’re still having trouble getting the pairing gesture to work properly, it’s 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.