Search documentation...

K
ChangelogBook a demoSign up

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:

ParameterTypeDescription
writeKeyStringThe write key used to identify the source in Hightouch.
collectDeviceIdBooleanWhether to autocollect a device ID via the Android DRM API. The ID is stored in context.device.id on all events. This is only supported on Android, and is disabled by default.
debugBooleanWhether to generate debug logs. Defaults to true.
loggerLoggerCustom logger instance to redirect internal logging from the library.
flushAtNumberMaximum number of events to accumulate before sending to the Hightouch API. Defaults to 20.
flushIntervalNumberMaximum number of seconds to hold events before sending to the Hightouch API. Defaults to 30.
flushPoliciesArrayOptional advanced customization for how events are buffered before sending to the Hightouch API.
maxBatchSizeNumberThe maximum number of events to send in one HTTP request to the Hightouch API. You may want to adjust this if your events are extremely large. Defaults to 1000.
trackAppLifecycleEventsBooleanWhether to automatically track lifecycle events like Application Installed. Defaults to false.
trackDeepLinksBooleanWhether to automatically track deep links. Only supported for Android. Defaults to false.
proxyStringUsed to override the URL used for sending events to Hightouch. This should contain the full path, e.g. https://us-east-1.hightouch-events.com/v1/batch

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:

ParameterTypeDescription
userIdStringThe user's persistent ID.
traitsObjectAdditional traits about the user, such as email and name.

Track

The track method is used to send a track event.

Method signature:

htClient.track(event, [properties])

Method parameters:

ParameterTypeDescription
eventStringThe event name (for example "Checked Out").
propertiesObjectAdditional properties about the event, such as product_id.

Screen

The screen method is used to send a screen event.

Method signature:

htClient.screen(name, [properties])

Method parameters:

ParameterTypeDescription
nameStringThe screen's name. For example, "Getting started".
propertiesObjectAdditional properties about the event.

Group

The group method sends a group event.

Method signature:

htClient.group(groupId, [traits])

Method parameters:

ParameterTypeDescription
groupIdStringThe id for the group.
traitsObjectAdditional traits about the group, such as company_name.

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.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Mar 20, 2024

On this page

InstallationiOSAndroidSDK InitializationManual tracking APIIdentifyTrackScreenGroupResetOut of the box eventsLifecycle eventsAdvertising identifiersAndroid AAIDiOS IDFA

Was this page helpful?