iOS Event Visualizer


Heap’s Event Visualizer for iOS allows you to easily define 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 with the iOS Event Visualizer

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

The Event Visualizer 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:

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 Event Visualizer screen will provide a confirmation:

Using the iOS 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 as seen below:

The events are displayed with the most recent interaction appearing at the top of the list. When an event is captured by Heap, the Event Visualizer will also capture a screenshot of where in the app the interaction occurred at the time of the event. This is only captured while the Event Visualizer is paired - it will not capture screenshots from live production users.

Selecting one of the items in the event list will bring up the Event Definition dialog, where you can define events. Events can be defined as is, using the pre-populated data:

By clicking the More Options button, additional filters and criteria can be specified to adjust the event definition:

iOS Developers: Enabling Event Visualizer Pairing

The iOS Event Visualizer utilizes a pairing flow to ensure 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] has been called, you will be able 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 is 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 Defining iOS 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 iOS 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, 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 which provides the name of the ViewController, though that event can be re-defined with a name that fits into your event taxonomy.

Common properties for defining screenviews:

  • View Controller

Defining Touch Events

In iOS apps, touch events occur on UI elements called UIViews. Depending on the structure of the app 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 code, and will generally uniquely identify the UI element. Sometimes Heap is not able to capture the Target View Name. In these situations, oftentimes a combination of other properties can be used to define 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 define 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 defining touch events:

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

Defining Action Method Events

It is 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 defining 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 defining action methods:

  • Action Method
  • Target View Class
  • View Controller

Defining Field Edit Events

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

Common properties for defining field edit events:

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

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 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 will generally not appear in the Event Visualizer. It is recommended to use the Live View, Events View, or Users View to define these events.

Common properties for defining app install/upgrade events:

  • Is Upgrade
  • Current Version Code

Enriching Autocaptured Data

On occasion, autocaptured data will 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 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 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 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 Target accessibilityLabel` 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 [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.


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 28 days ago

iOS 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.