From Classic to Core - React Native Edition

If you're using Heap's Classic React Native SDK and you're thinking about upgrading to our latest Core SDK offerings, there are a few differences you'll want to be aware of to help inform that decision.

SDK Configuration

Heap's Classic React Native SDK is an "autocapture by default" solution. This means that the SDK is built to primarily enable autocapture with custom tracking being a secondary use case. Advanced configuration is required to disable the autocapture behaviors in the Classic SDK, but disabling autocapture can also lead to some properties, such as library version or build type, not being captured.

In the Core SDKs, we've reworked our offerings so that we start with custom tracking and a set of standard APIs first. Everything you need to track events, identify users, and add user and event properties is available through our custom tracking SDK. If you want to add autocapture on top of that, it's as easy as adding our autocapture SDK and BabelJS plugin, along with a single line of code, to get that setup. No advanced configuration is needed to enable or disable autocapture.

Configuration Summary

Configuration Methods

The Core React Native SDK does not offer automatic initialization. Instead, you can use Heap.startRecording in your app's code Ideally, this should be executed once, but calling the method multiple times with the same options is safe.

Heap can also be de-initialized using Heap.stopRecording, supporting behavior like analytics opt-out.

Autocaptured Events

The Core React Native SDK captures all of the same events as Classic SDK. There are two changes to events that will affect autocapture.

• Edits to text fields will now show up as "Change on" rather than "Field edit" events. This brings the React Native SDK in line with the other SDKs, which produce a single event type for form field changes.
• React Native screen views are now saved as pageviews rather than events. Again, this brings the SDK closer to the other SDKs.

Autocaptured Properties

The React Native hierarchy has been refined in a few ways. These are all designed to simplify event creation, but can impact migration between the two SDKs.

• testID is now used for IDs in hierarchy, so <Button testID="add-to-cart" /> will show up as Button#add-to-cart rather than Button[testID=add-to-cart] by default.

  📘

  To match existing event definitions on testID, you can use the preserveTestIdProp registration option:

  JavaScript

  registerHeapAutocapture({
    isDefault: true,
    preserveTestIdProp: true,
  });
  

• When using React Navigation, the hierarchy will end at the screen rather than continuing through the navigation library's internal views. This will produce shorter, and easier to read, hierarchies.
• When interacting with elements like <Button />, the touched view will be reported as Button rather than the internal TouchableOpacity. This will also make it easier to create events and get meaningful event properties.
• When using <HeapIgnoreText />, properties that are known to display text are automatically excluded from the hierarchy.
• Duplicate views from HOCs are omitted from the hierarchy.

Additionally, the "Screen Name" property no longer returns the inner-most component and instead returns the same value as "Screen Path".

Pageview support

The Core SDK has two distinct improvements over the Classic SDK:

• React Native Navigation 7.0 and later are now supported. Apps using this library will now see autocaptured pageviews.
• React Navigation 5.0 and later no longer need manual instrumentation with withReactNavigationAutotrack. This function is still safe to call but can be removed from the app.

Event Creation

Heap Classic events are commonly created via either the live data feed or visual labeling. Visual labeling has the added benefit of being able to create an event using the hierarchy of the UI component that was interacted with, which isn't visible for events created via the live data feed with the Classic SDK.

In Heap Core, events are primarily created via the live data feed. The visual labeling interface is not currently supported for Heap Core. Autocaptured events from Heap Core will include their hierarchy in the live data feed to allow this property to be used in events.

🚧

Visual Labeling Support

If the visual labeling interface is a core part of your workflow in Heap, we do not recommend switching from Classic to Core at this time.

Creation Methods

Users and Installs

The Core SDK does not read from or write to the same storage location as the Classic SDK. Because of this, switching to the Core SDK will cause a temporary spike in new users and install events, as if you were seeing all of your users for the first time. This spike is temporary and will level out once all users have upgraded to a version of your app that uses the Core SDK.