Migrating legacy React Native events for Heap 0.9.0


Prior to version 0.9.0, Heap’s React Native SDK sent autocaptured eventsevents - Actions users take on your site or in your app. Events are the basic building blocks of reports. as custom events. We do this by sending events that are autocaptured in the JavaScript layers of React Native through to our native SDKs (which the React Native SDK depends on) as custom events. Within Heap's analysis modules, they appear to be the same as any other event that was sent via a Heap.track() call. This was a non-optimal experience for defining and using React Native events throughout Heap, and upcoming changes to the React Native SDK are meant to improve on this.

In Heap for React Native v0.9.0, we’ve rearchitected the format of autocaptured React Native events, as well as how these events are sent to Heap’s backend. This will make it more intuitive – and much easier – to define events on top of raw autocaptured React Native data.

These upgrade notes aim to explain how this new eventevent - Action users take on your site or in your app. Events are the basic building blocks of reports. format differs from the previous event format, what breaking changes you need to worry about, and how to remediate these breaking changes.

Old Format vs New Format

As mentioned above, the existing autocaptured event format was entirely based on custom events. This means that an event definition describing a “touch” event on a “Basics” button in the navigation tab bar might look like this:

Our new format aims to improve on this in a number of ways:

  • We will introduce a new React Native event source, which will make it clearer how to define a virtual event for React Native.
  • Event Properties will now appear as built-in properties with consistent naming and casing that matches events in other platforms/SDKs.
  • The touchableHierarchy property will be renamed to the React Native Hierarchy, and will support CSS selectors similarly to how they are supported for web events.
  • Raw autocaptured events will now correctly be identified as raw events that can be virtualized, and can be ignored in analysis modules like the Users View.

With these improvements, the above definition of the touch on the Basics button in the navigation bar will look more like this (though the iconography will change slightly in the final version):

Breaking Changes

Because the format for data sent with Heap for React Native v0.9.0 and later is different from v0.8.0 and earlier, most event definitions will need to be adjusted when upgrading your app to use v0.9.0.


  • All property and event names have changed: e.g. touchableHierarchy is now React native hierarchy, touchableHandlePress is now Touch on, etc. A full mapping of old to new names is provided in the Creating the new event section of this doc.
  • The format for React hierarchies has changed. Previously, the format was ;[<component prop>=<component prop value>];|. The format is now @<component name>;[<component prop>=<component prop value>];|, the difference being the @ sign in front of component name. For example, hierarchy that looked like SignUpScreen;|SignUpForm;|Button;[title=Log In];|TouchableOpacity;| will now look like @SignUpScreen;|@SignUpForm;|@Button;[title=Log In];|@TouchableOpacity;|. This change makes React Native hierarchies consistent with web, iOS, and Android hierarchies.
  • The event source is now React Native, and not Android or iOS. This may break reportsreports - saved analysis results which you can continually re-run to monitor your analytics. and analyses that rely on the Source property being a mobile platform. The platform (iOS/Android) the event came from is now captured in the Platform Type property.

Remediating Breaking Changes

For each event definition on a pre-v0.9.0 React Native Heap event, you will need to do the following (details for each step are described below):

  1. Create a new event definition that corresponds to the old event using the data format sent by RNHeap v0.9.0 and later

  2. Create a combo event consisting of the pre-v0.9.0 RNHeap event and the RNHeap v0.9.0 event

  • Change references to the old event to point to the combo event

Creating the new event

The first step in fixing a broken event definition caused by an upgrade to RNHeap v0.9.0 is to create an equivalent event based on the new event format. This can be done one of two ways:

  • Map the event type (e.g. touchableHandlePress) and event properties (e.g. touchableHierarchy` targetText, etc.) to the new event type (e.g. Touch on) and new event properties (e.g. React native hierarchy, Target Text, etc.). This can be slightly faster, and so it’s preferable if you’re updating many event definitions. However, this can be slightly more error-prone.
  • Define the event as if you’re defining the event for the first time. I.e. perform the event in the app, and define the event using your preferred method (Live view, Users view, Events view). This is easier and less error-prone, though it may also be a little slower, so is preferable if you’re only updating a few definitions.

If you’re using the second method, define the new events like normal.

If you’re using the first method, do the following to define new events:

  1. In the Events view, start creating a new event by clicking New Event. We recommend doing this in a new tab to allow you to quickly navigate between this new event and the event you’re migrating.

  2. Name the new event. We recommend a format like - RNHeap > v0.9.0. So for an old event called Nav - Touch Basics Button, the new event would be named Nav - Touch Basics Button - RNHeap > v0.9.0. Feel free to use a different format if you prefer.

  3. Set the Source to React Native.

  4. Set the Event type based on the old event type’s mapping. The event type mappings are as follows:

  • touchableHandlePress → Touch on
  • touchableHandleLongPress → Touch on
  • _handleChange → Change on
  • textEdit → Edit field
  • scrollViewPage → Page transition
  • reactNavigationScreenview → View screen
  1. For each filter on the old event, create a corresponding filter on the new event. This is done by mapping the old property name to the new property name, and setting the value to be the same as the old definition.

Note: some properties, like App Name and Platform, won’t need to be mapped. If the property isn’t in the mapping below, simply recreate an identical filter on the new event.


Make sure the operator for the new event filter is the same as the old event filter. See the property mappings below.

  • touchableHierarchy → React Native hierarchy (Note: depending on the original value for filters on this property, additional changes may be needed. See Fixing hierarchies below for additional information.)
  • targetText → Target Text
  • type → Navigation Action
  • path → Screen Path
  • screenName → Screen Name
  • pageIndex → Page Index
  • touchState → Touch State
  • placeholderText → Placeholder Text
  • Source → Platform Type (Source will now always be React Native)

If the old event definition is based on touchableHandlePress, add a filter for Is Long Press equals false. If the old event definition is based on touchableHandleLongPress, add a filter for Is Long Press equals false.

You may want to skip this step if you don’t want to limit the definition to whether the touch was a long press. This is generally the case if a short touch does the same thing as a long press.

Last but not least: save the event.

Adjusting hierarchies

Because of the change to the format of hierarchies mentioned above, some filters on hierarchies may need to be modified beyond changing the property name. Even when filters don’t need to be modified, there are cases where these filters should be modified to ensure the desired level of specificity for the event.

Hierarchy filters that match on multiple component name, (e.g. touchableHierarchy contains BasicsButton;|TouchableOpacity;| should be changed to include an @-sign in front of the hierarchy, e.g. React Native Hierarchy contains @BasicsButton;|@TouchableOpacity;|. We also strongly recommend doing this for filters that match on single-component names as well, e.g. touchableHierarchy contains BasicsButton;[key=Foo];| should be changed to React Native Hierarchy contains @BasicsButton;[key=Foo];|.

For event definitions with multiple filters on touchableHierarchy, it may be preferable to use hierarchy matchers for a more robust definition. The structure of these matchers is described in Events: Tags, Classes, and Ids, where React component names take the place of tags, and component props take the place of attributes. The matcher should be placed in the “React hierarchy selector” text box, next to the event type.

Creating a combo event

Once you’ve created the new version of the event, it’s time to create the combo event that will replace the old event:

  1. Rename the old event. We recommend the format <old event name> - RNHeap < v0.9.0.
  2. Create a new event.
  3. Give the event the same name as the old event.
  4. Set the Source to Combo.
  5. Click Add Event twice.
  6. In the first event drop-down that appears, select the old event.
  7. In the second event drop-down that appears, select the event you just created.
  8. Save the event.

Updating Event References

Once the combo event is created, congratulations! You’ve successfully updated the old event definition to represent both the old and new formats. Now, it’s time to update any references to this event definition.

Update Reports

To update reportsreports - saved analysis results which you can continually re-run to monitor your analytics., do the following:

  1. Determine whether the old event was used in any reports:
  • Go to the old event in the Events view
  • Find the text X reports include this event statement in the summary at the top
  1. If no reports include this event, no action is needed; continue on to the Segments section below

  2. If some number of reports include this event, click the number to see which reports include the event, and do the following for each report:

  • Open the report in two different tabs - one to view the original report, one to modify the report
  • Change the reference to the old event to the combo event
  • Copy all filters from the original report
  • For any filters using props listed under Creating the new event above, do the following:
    • Click the icon immediately to the right of the filter to create a nested filter
    • Change this nested filter to an OR
    • Set the property for the second filter within the nested OR filter to the new property based on the mapping under Creating the new event above
    • Set the value to be the same as the original filter
  • For any group-by’s using the props listed under Creating the new event above, the process is a bit more complicated:
    • In a new tab, open the Properties view under Define
    • Create a new property
    • Call the property <new property name> w/ RNHeap < v0.9.0. So if the group-by is on targetText, you’d call the property Target Text w/ RNHeap < v0.9.0
    • For the first case, set the condition to is defined, and set the value to the old property
    • For the second case, set the condition to is defined, and set the value to the new property
    • Save the defined property
    • In the report, replace the old property with the property you just defined

Last but not least, save the report.


Currently, there is no way to quickly identify which segments an event is used in. You’ll need to go through each individual segment and change the old event to the combo event if it’s present. We recommend doing this after all events are updated to combo events to avoid scanning through all your project’s segments multiple times.