Overview
The Event Visualizer is Heap’s simple point-and-click interface for defining events. Instead of manually logging events within code, you can define events by simply clicking around your website or app. No coding knowledge is required, though it is useful for refining your event definitions further.
Select Webpage & Launch Visualizer
To use the Event Visualizer for websites and web apps, navigate to the Event Visualizer page in Heap. Click the text box to select from a menu of top viewed pages on your website or enter a URL in the text box.
Click Launch to launch the Event Visualizer overlay on the selected page.
Using the Event Visualizer to Capture & Define Web Events
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 screenshot below, we’ve clicked on the Get Demo 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 (#menu-header in the screenshot above).
Selecting only one of the navigation bar elements will look like this in the Event Visualizer.
Definition: You can review the event definition contextually within the CSS of the page to ensure the scope of the event definition is correct.
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.
Doing this won’t break your event definition – try clicking on different CSS elements and checking what gets captured to further optimize your new event.
Property Suggestions
If your event definition includes data attributes, you will see the 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 & Request Verification.
To see your brand-new event definition, click Back to Heap at the top to navigate back to your Heap workspace. 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 defining events in the Event Visualizer via the web, 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 defining the event in the Event Visualizer.
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 section on Defining Events in the Events Tab.
Example: Capture Clicks On Signup Wherever It Appears
Many users have elements that exist on multiple pages of their website, such as a signup button. If an element has the same CSS hierarchy on all pages, then your 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 the Event Visualizer, see our FAQ I can’t get the Event Visualizer 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 the Event Visualizer 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 the Event Visualizer 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
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.
The iOS Event Visualizer will not work for a React Native install. To use the Event Visualizer for React Native, see the React Native version of this guide.
Pairing a Device or Simulator
There are two options for pairing your device with the iOS Event Visualizer. 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 Event Visualizer Pairing to be able to complete the instructions below.
Navigate to the Event Visualizer 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 Event Visualizer’s 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 Event Visualizer page 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 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 Event Visualizer screen will provide a confirmation:
Using the iOS Event Visualizer to Capture & Define Virtual Events
View events will not appear in the list of event activity when using the Event Visualizer. We recommend filtering via Live View to define view events instead of the Event Visualizer.
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.
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
View events only appear in the list of event activity when using the Event Visualizer with Heap versions 7.3.0 and above. We recommend using Live View to define view events instead of the Event Visualizer.
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 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 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 Event Visualizer 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 Event Visualizer screenshots
When using the Event Visualizer, 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 the Event Visualizer 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 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 the Event Visualizer page 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:
- 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 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:
- 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. 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:
- 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 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.
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 Event Visualizer screenshots
When using the Event Visualizer, 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 the Event Visualizer 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.
If you’re running React Native SDK version 0.9.0 and above, you can define React Native events via the Android Event Visualizer. 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.
If you’re running a React Native SDK version below 0.9.0, or if you have legacy events from before that version you are migrating to the new version, see Migrating legacy React Native events for Heap 0.9.0.
Though the iOS Event Visualizer cannot currently be used to define React Native events, React Native events defined via the Android Event Visualizer will apply to iOS, as well.
To pair your device or emulator with the Event Visualizer, navigate to the Event Visualizer page in Heap, then click the Android tab. Follow the steps on that page to pair your device or emulator.
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.
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.