Overview
You can use visual labeling in Heap to select and define raw bits of data as events, which you can then use in analysis. No coding knowledge is required, though it is useful for refining your events further after they’ve been labeled.
Note that we only officially support visual labeling in the Chrome browser.
To visually label websites and web apps, navigate to the Visual labeling page in Heap. Enter the URL for your website in the text box, or select one of your top-viewed pages from the drop-down.
Explore pageview suggestions
This section will take you to a list of the most popular pageviews within your app. Defining pageviews as events allows you to dig into engagement with those pages to better understand user behavior. For more info, see Pageview Suggestions.
Click Launch to launch the visual labeling interface on your selected page. Once it loads, it will look like this:
If the visual labeling toolbar is blocking an element you want to define an event on, simply click the arrow at the bottom to minimize it.
To define new events, simply hover over and click on the element you’d like to define an event for. Once clicked, a pop-up will appear where you can review and update the definition of the event as needed before saving it.
In the visual labeling toolbar you will notice options to Define Events and Navigate Site. The Define Events mode will allow you to define the event based on your clicks/interactions. The Navigate Site mode allows you to use the site regularly so you can get to the interaction you eventually want to define.
To switch modes you can either click on the mode you want in the toolbar, or use the keyboard shortcut (Ctrl + /). For German keyboards, the shortcut is Ctrl + Shift + ß and for Swiss German keyboards the shortcut is Ctrl + Shift + ‘. The keyboard shortcut is helpful to switch modes without triggering subsequent click interactions on your site.
In the screenshot below, we’ve clicked on the Free Trial button on our homepage. To the right, some helpful information is provided which you can review to confirm that you are defining the right event.
The information listed on this screen includes:
Amount of clicks in the past week: Reference this number to make sure you’ve selected the right event. If it’s one that typically gets a lot of traffic, but this number is low, then you may need to adjust your event definition.
Number of matching elements on this page: If you intended to select an element that appears more than once, such as a list with multiple elements, you can check this number to confirm your selection is correct.
For example, you may wish to know when any element of a navigation bar is selected. You can hover over the navigation bar to select all of the elements in that space.
When defining an event, you can check the selector to confirm that it applies to the entire nav bar (.site-nav__list in the screenshot above).
Selecting only one of the navigation bar elements will look like this.
Within the Edit Definition section, you can hover over each individual CSS element to see what it selects on the page. Clicking on an element adds it to your event definition, enabling you to further define your new event from this page based on what you want to capture.
Scroll to the right to see the full event definition.
Clicking on different elements won’t break your event definition. You can experiment by clicking on different CSS elements to see what gets captured, allowing you to further optimize your new event definition.
Property Suggestions
If your event definition includes data attributes, you”ll see an option to add these to your event definition by selecting the checkbox next to the attribute. This is helpful for adding useful metadata to an event.
Additional Filters
The following filters may appear based on the context of the event you are defining.
Additional Filters
Limit to Text: This allows you to narrow the event definition based on the text in the element.
Limit to URL: This allows you to narrow the event definition to only instances where the event occurs on this page.
You may also see warning messages if you are defining an event that already exists in your Heap app, if there is no data associated with the event, or if the event matches what we know to be a bad pattern (such as being too wide in scope).
Once you’ve tailored your event definition to your needs, click Next. On the next page, you’ll see options to name and categorize your new event. You can define an event in your personal or shared space.
You’ll have the chance to review your event definition one last time before saving. At the bottom of the page, you can add notes to give a deeper description of what this event is capturing. When you’re ready to save your new event, click Define Event.
To see your brand-new event definition, click the Back to Heap button at the top to navigate back to your Heap account. You’ll also see options to QA with Live View and define pageviews in this top navigation bar.
Not familiar with CSS? Take our 30-minute Intro to HTML & CSS course to quickly ramp up to creating and managing your very own event definitions.
Best Practices
When visually labeling events, we recommend the following best practices.
Always select the largest element possible. This includes all clicks that could occur inside the highlighted event.
Example: Capture All Clicks on Blog Post CTA
As an example, we may want to capture all clicks on a blog post on your homepage, including clicks on the title, image, and surrounding space within that element. To make sure all of these actions are captured, we will select the entire element when labeling the event.
If you define the event on only the title of the blog post, then you’ll miss clicks on the other parts that also lead to that link.
Be careful when using dynamic CSS IDs or classes, which includes most IDs you see with a random string of numbers or classes (such as ember_12345) as these may limit the data captured to the extent that nothing appears in Heap. If you see no users have completed this action in your analysis, this means you probably have a dynamic CSS class or ID selected.
If too many elements are highlighted when you defined your event, you can narrow your definition by clicking on CSS elements to add them to your event definition.
If too few elements are highlighted, you can expand your definition to include the elements you want to capture by clicking on them within the edit definition section.
To better understand how CSS selectors work, check out our guide on Defining Events in the Events Tab.
Example: Capture Clicks On Signup Wherever It Appears
Many websites have elements that exist on multiple pages, such as a signup button. If an element has the same CSS hierarchy on all pages, then this event will be defined across all pages.
If you only want to look at the event on a specific page, then make sure to check the ‘Limit to URL‘ box when defining the event. This ensures that the event definition will only apply to the path, and not to all other pages where the same action is taken.
In this example, we highlight ‘Sign Up’ to define it as a new event. To make sure we are only tracking clicks on ‘Get Started’ on this specific page, we check ‘Limit to URL‘.
With that box checked, we don’t have to worry about unintentionally capturing clicks on the same ‘Sign Up’ button on other pages.
Troubleshooting Common Errors
For errors using visual labeling, see our FAQ I can’t get visual labeling to work. Why?
React & Angular Websites
Is your app built in a single page app framework, such as React or Angular? If so, be sure to write distinct classes or IDs or make use of data-attributes so that you can accurately define events based on those selectors.
Browser Compatibility
We only support visual labeling for the latest version of Chrome on desktop. Mobile browsers are not supported. Other desktop browsers, including Firefox, Safari, Edge, and all others, are not supported.
If you are having any trouble with visual labeling on Chrome, you should check to ensure you are on the latest version of Chrome. For steps to do so, see Google’s support documentation.
Overview
You can use visual labeling 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
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
You must complete the installation steps in enable visual labeling to be able to complete the instructions below.
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 defined. 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 cannot 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 provide a confirmation:
Using iOS visual labeling to Capture & Define Virtual Events
View events will not appear in the list of event activity when using visual labeling. We recommend filtering via Live View to define view events instead of via visual labeling.
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 definitions (if the event is defined).
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 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.
iOS Developers: Enabling visual labeling Pairing
iOS visual labeling 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. 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.
Defining Screenview Events
View events only appear in the list of event activity when using visual labeling with Heap versions 7.3.0 and above. We recommend using Live View to define view events instead of visual labeling.
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-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:
- Hierarchy
- 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 visual labeling. 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 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 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.
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 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 define 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.
Overview
Heap’s visual labeling 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 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:
- Press the Volume Up button three times.
- Press the Volume Down button three times.
- Press the Volume Up button three times.
- 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 Define 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 definitions (if the event is defined).
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 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
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:
- A large number of devices becoming pairing candidates.
- 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. 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.
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:
- First fragment transition: MovieDetailsFragment is added
- Activity transition: MovieDetailsActivity is loaded
- 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 visual labeling. 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.
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 define 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.
Overview
If you are running React Native SDK version 0.19.0 and above, you can define React Native events via the iOS or Android visual labeling. This gives you access to the React Native hierarchy, which is the primary property for defining events. This allows you to refine touch, edit, and page transition event definitions via the tree of events in the hierarchy.
Pairing a Device or Emulator
To pair your device or emulator with visual labeling, navigate to the visual labeling page in Heap, then click the iOS or Android tab, depending on the device you are testing. Follow the steps on that page to pair your device or emulator.
More detailed pairing instructions can also be found on the iOS and Android tabs of this document.
To pair visual labeling using an iOS QR code, you must complete the installation steps in Enable visual labeling pairing from the iOS Installation Guide.
You’ll see your device pop up on the left, with all of the corresponding app interactions you can use as event definitions in the middle pane. When you click on an event, options to define that event will appear on the right.
Defining Events
When defining touch, edit, and page transition events, the React Native hierarchy will appear in the Select Target pane. Feel free to click around on elements in the hierarchy to further refine your event definition.
When you’re ready to define your event, click the Define Event button further down the page. Once the event is defined, you can confirm that matching is happening properly in the Live View, or by analyzing the event from the Events view.
Information about how to use hierarchies in event definitions is available Managing React Native Event Definitions.