React Native SDK

​

Installation

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

npx pod-install

​

Android

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

​

SDK Initialization

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

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

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>
);

​

Session tracking

• foregroundSessionTimeout limits inactivity while the app is in the foreground.
• backgroundSessionTimeout limits how long the app can stay in the background before the next resume starts a new session.

• First launch, when no session state is persisted.
• Foreground inactivity exceeds foregroundSessionTimeout.
• Resume after being backgrounded longer than backgroundSessionTimeout, including after process death.
• Calling reset().

const htClient = createClient({
  writeKey: 'API_KEY',
  foregroundSessionTimeout: 60 * 60 * 1000,
  backgroundSessionTimeout: 60 * 60 * 1000,
});

​

Manual tracking API

​

Identify

htClient.identify(userId, [traits])

​

Track

htClient.track(event, [properties])

​

Screen

htClient.screen(name, [properties])

​

Group

htClient.group(groupId, [traits])

​

Reset

htClient.reset()

​

Flush

await htClient.flush()

// Ensure a purchase event is sent immediately
htClient.track("Order Completed", { orderId: "12345", total: 59.99 });
await htClient.flush();

​

Flush behavior

• Count threshold (flushAt): The queue accumulates 20 events (configurable via the flushAt option in createClient).
• Time interval (flushInterval): 30 seconds have elapsed since the last flush (configurable via the flushInterval option in createClient).

​

Flush policies

• CountFlushPolicy(limit) — flushes after a specified number of events accumulate. This is the policy behind the flushAt default.
• TimerFlushPolicy(intervalMs) — flushes on a recurring time interval (in milliseconds). This is the policy behind the flushInterval default.
• BackgroundFlushPolicy() — flushes automatically when the app is sent to the background. This is useful for ensuring events are sent before the OS suspends your app.
• StartupFlushPolicy() — triggers a single flush immediately when the client starts. This is useful for sending any events that were queued from a previous session.

import {
  createClient,
  CountFlushPolicy,
  TimerFlushPolicy,
  BackgroundFlushPolicy,
  StartupFlushPolicy,
} from "@ht-sdks/events-sdk-react-native";

const htClient = createClient({
  writeKey: "API_KEY",
  flushPolicies: [
    new CountFlushPolicy(10), // Flush every 10 events
    new TimerFlushPolicy(15 * 1000), // Flush every 15 seconds
    new BackgroundFlushPolicy(), // Flush when the app is backgrounded
    new StartupFlushPolicy(), // Flush any queued events on startup
  ],
});

const backgroundPolicy = new BackgroundFlushPolicy();

// Add a policy after initialization
htClient.addFlushPolicy(backgroundPolicy);

// Remove a policy later
htClient.removeFlushPolicy(backgroundPolicy);

​

Anonymous ID management

​

Get the anonymous ID

// Async (recommended) — waits for storage to be fully restored
const { anonymousId } = await htClient.userInfo.get(true);

// Sync — returns the current in-memory value immediately
const { anonymousId } = htClient.userInfo.get();

​

Set or override the anonymous ID

await htClient.userInfo.set((state) => ({
  ...state,
  anonymousId: "my-custom-anonymous-id",
}));

• Migrating from another vendor. If your app previously used a different analytics SDK, you can carry over the existing anonymous ID so that pre- and post-migration events are attributed to the same device.
• Using your own device identifier. If your app already generates a stable device ID, you can use it as the anonymous ID to simplify identity resolution.

​

Relationship between anonymousId and userId

// Reset everything including anonymousId (default)
await htClient.reset();

// Clear userId and traits but keep the current anonymousId
await htClient.reset(false);

​

Out of the box events

​

Lifecycle 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.

​

Prebuilt plugins

​

Braze

npm install @ht-sdks/events-sdk-react-native@^3 @ht-sdks/events-sdk-react-native-plugin-braze@^1 @braze/react-native-sdk@^5
npx pod-install

import { createClient } from "@ht-sdks/events-sdk-react-native";
import { BrazePlugin } from "@ht-sdks/events-sdk-react-native-plugin-braze";

const htClient = createClient({
  writeKey: "YOUR_WRITE_KEY",
  defaultSettings: { integrations: { Appboy: {} } },
});

htClient.add({ plugin: new BrazePlugin({ forwardScreenViews: true }) });

​

Advertising identifiers

​

Android AAID

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

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.

​

Tips and troubleshooting

​

Missing events

1. Upgrade to the latest SDK version. Run npm install @ht-sdks/events-sdk-react-native@latest to pick up the most recent bug fixes and delivery improvements.
2. Add a manual flush after critical events. The SDK buffers events for up to 30 seconds by default. Although queued events are persisted and retried on the next app launch, calling await htClient.flush() immediately after high-value events like purchases or sign-ups ensures they are delivered promptly rather than waiting for the next flush cycle or app session.
3. Add a BackgroundFlushPolicy. This ensures the queue is flushed whenever the app moves to the background, covering cases where users leave the app between automatic flush cycles. You can add it at runtime without replacing your existing policies:
   import { BackgroundFlushPolicy } from "@ht-sdks/events-sdk-react-native";
   
   htClient.addFlushPolicy(new BackgroundFlushPolicy());
   
4. Enable debug logging. Set debug: true in createClient (this is the default) and check device logs for errors during event delivery.
5. Verify your write key. Confirm that the writeKey in createClient matches the write key shown on your event source in Hightouch.