React Native SDK

The React Native SDK makes it easy to track events in React Native applications. The SDK supports Both iOS and Android applications.

Installation

The React Native SDK is distributed via npm.

Install the required dependencies into your React Native project via npm:

npm install --save \
  @ht-sdks/events-sdk-react-native \
  @ht-sdks/sovran-react-native \
  react-native-get-random-values \
  @react-native-async-storage/async-storage

iOS

On iOS, you will also need to install the native modules by running:

npx pod-install

Android

The SDK requires additional permissions on Android in order to populate the device context for events.

Add these permissions to your app by updating your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

SDK Initialization

Once the dependencies are installed, you can import the tracking client into your application.

import { createClient } from '@ht-sdks/events-sdk-react-native';

const htClient = createClient({
  writeKey: 'API_KEY'
});

The client can either be passed around explicitly throughout your app, or exposed through a React context hook. To pass the context through a Context, use AnalyticsProvider and useAnalytics.

import { AnalyticsProvider } from '@ht-sdks/events-sdk-react-native';

// The Child component can retrieve the htClient by calling `useAnalytics()`.
const App = () => (
  <AnalyticsProvider client={htClient}>
    <Child />
  </AnalyticsProvider>
);

The client may be configured with the following options:

Manual tracking API

Identify

The identify method is used to send an identify event.

If identify is called multiple times for the same user, the traits are merged together.

Method signature:

htClient.identify(userId, [traits])

Method parameters:

Track

The track method is used to send a track event.

Method signature:

htClient.track(event, [properties])

Method parameters:

Screen

The screen method is used to send a screen event.

Method signature:

htClient.screen(name, [properties])

Method parameters:

Group

The group method sends a group event.

Method signature:

htClient.group(groupId, [traits])

Method parameters:

Reset

The reset method resets the identify calls for the local session. Specifically, it resets the anonymousId, userId, and traits.

The reset method should be called when users log out. This way, if the user logs back in with another account, the userIds and traits from the different sessions remain separate.

Method signature:

htClient.reset()

Out of the box events

Lifecycle events

When trackAppLifecycleEvents is enabled, Hightouch automatically tracks the following events:

• Application Installed -- Emitted when the app is first opened after a new install.
• Application Updated -- Emitted when the app is first opened after upgrading from a previous version.
• Application Opened -- Emitted whenever the app is opened (including when it's resuming from the background).
• Application Backgrounded -- Emitted whenever the app is backgrounded.

Advertising identifiers

To collect IDFAs and AAIDs for advertising identification, you may use the @ht-sdks/events-sdk-react-native-plugin-advertising-id and @ht-sdks/events-sdk-react-native-plugin-idfa packages.

These plugins load native modules that pull the local advertising ID.

Android AAID

Once setup, the AAID will be stored in context.device.advertisingId

1. Add the Android AAID plugin to your project.

   npm install @ht-sdks/events-sdk-react-native-plugin-advertising-id
   

2. Add the plugin to your code by adding the following code after initializing your client.

   htClient.add({plugin: new AdvertisingIdPlugin()});
   

3. Update your Android application manifest to include your AdMob app ID.

   <manifest>
     <application>
       <!-- Sample AdMob app ID: ca-app-pub-3940256099942544~3347511713 -->
       <meta-data
           android:name="com.google.android.gms.ads.APPLICATION_ID"
           android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
     </application>
   </manifest>
   

iOS IDFA

Once setup, the IDFA will be stored in context.device.advertisingId

1. Add the iOS IDFA plugin to your project.

   npm install @ht-sdks/events-sdk-react-native-plugin-idfa
   

2. Add the plugin to your code by adding the following code after initializing your client.

   htClient.add({plugin: new IdfaPlugin()});
   

3. Update your Info.plist to set NSUserTrackingUsageDescription. This description will be displayed when prompting users for permission to track their IDFA.