React Native SDK (client)
Install the Ours Privacy React Native SDK to capture privacy-first analytics in React Native and Expo apps. Pure JavaScript, with no native modules, no IDFA, and no ATT prompt on iOS.
Use the Ours Privacy React Native SDK to track events, identify users, and collect app opens, sessions, and screens from your iOS and Android apps. It is pure JavaScript, so it works in React Native and Expo apps without native modules.
- npm package
- GitHub repository: full README, API reference, and release notes
Install
npm install @oursprivacy/react-native @react-native-async-storage/async-storage@react-native-async-storage/async-storage is optional. It keeps the visitor ID and unsent events across app restarts; without it, the SDK holds them in memory.
Quick Start
Create one instance for your app and initialize it with your source's API token:
import { OursPrivacy } from '@oursprivacy/react-native';
const op = new OursPrivacy();
await op.init('YOUR_API_TOKEN');
op.track('App Opened');
// After login
await op.identify({ externalId: 'user-123', email: 'user@example.com' });Events are batched and sent every 10 seconds. Call await op.flush() to send them immediately, and await op.reset() on logout to start a new visitor. For default properties, a custom server URL, and the rest of the API, see the README on GitHub.
Wait for consent
If your app asks for consent first, start opted out and opt in once the person agrees:
await op.init('YOUR_API_TOKEN', { optOutTrackingByDefault: true });
// When consent is granted
await op.optInTracking();optOutTrackingByDefault applies only until a choice is saved, so a returning user keeps the choice they made. While opted out, the SDK sends nothing. await op.optOutTracking() also clears unsent events, and the next opt-in starts a new session.
App lifecycle and screens
Turn on automatic lifecycle tracking to fill in app opens, sessions, and engagement in Mobile Analytics. It is off by default. Pass your app's version and build so you can follow release adoption:
await op.init('YOUR_API_TOKEN', {
trackAutomaticEvents: true,
appVersion: '2.0.0',
appBuild: '42',
});| Event | When it is sent | Event-specific properties |
|---|---|---|
$mobile_first_open | First tracked app open for this installation and source | None |
$mobile_app_open | Each tracked foreground entry | None |
$mobile_session_start | First tracked open in a new session | None |
$mobile_session_engagement | A foreground-time checkpoint, screen change, or background transition | engagement_duration_ms; screen_name when known |
$mobile_session_end | When an expired session is observed, when possible | None |
$mobile_app_update | First tracked open after the app version or build changes | previous_app_version and previous_app_build when known |
$mobile_screen_view | Your app calls trackScreen() for a new visible screen | screen_name |
A session continues when the app returns to the foreground within 30 minutes, and counts as engaged after 10 seconds in the foreground. $mobile_session_end is best effort, because an app can close without warning.
The SDK does not see your navigator's route changes, so pass them in. For React Navigation, call trackScreen() on the initial route and on later route changes:
import { NavigationContainer, createNavigationContainerRef } from '@react-navigation/native';
const navigationRef = createNavigationContainerRef();
const screenLabels = new Map([
['HomeRoute', 'Home'],
['ScheduleRoute', 'Schedule'],
]);
function trackCurrentScreen() {
const route = navigationRef.getCurrentRoute()?.name;
const label = route && screenLabels.get(route);
if (label) op.trackScreen(label);
}
<NavigationContainer
ref={navigationRef}
onReady={trackCurrentScreen}
onStateChange={trackCurrentScreen}
>
<RootNavigator />
</NavigationContainer>;Pass a fixed label from a list in your app, such as Schedule: up to 80 characters, starting with a letter, using only letters, numbers, spaces, underscores, and hyphens. trackScreen() throws for any other label, so map route names to labels as above rather than passing them through. Never build a label from a URL, route parameter, patient detail, or screen content.
Manual track() and trackScreen() calls work whether or not lifecycle tracking is on. Send standard healthcare events with the same names and properties as your other sources.
Lifecycle and screen events carry device, OS, and app version details, but not your default properties or link attribution. Keep each event under 196 of your own properties and 1 MB; a larger event is still sent, but it doesn't appear in Mobile Analytics.
Web-to-app identity
When your app is opened by a link carrying ours_visitor_id, the SDK sets that visitor ID so later events land on the same visitor profile as their web activity. It also reads supported UTM parameters and ad-platform click IDs from the link, attaches them to the events you track afterward, and sends a $deep_link_opened event with those values (not the raw URL).
Hand the URL over with await op.trackDeepLink(url), and await it before your next track() so the visitor ID and attribution apply first. You can also pass the URL to init as initialURL. If your app already holds the visitor ID, from a WebView or a native bridge, set it directly with await op.setVisitorId('550e8400-e29b-41d4-a716-446655440000'). To pass the visitor ID to another SDK, such as a mobile measurement partner, read it with op.getVisitorId().
The SDK hooks nothing in the operating system, so your app has to hand over the URL it was opened with, on a cold start and on a warm open:
import { Linking } from 'react-native';
// Cold start
const initialURL = await Linking.getInitialURL();
if (initialURL) {
await op.trackDeepLink(initialURL);
}
// Warm open, app already running
Linking.addEventListener('url', async ({ url }) => {
await op.trackDeepLink(url);
});The UTM parameters and click IDs from a link last until the app quits; only the visitor ID persists across a restart. Pass the link to the SDK before you track an event that needs its attribution. Keep patient details out of the links you send people.
Mobile app attribution covers how app attribution works end to end, and when you need a mobile measurement partner alongside it.
Compatibility
- React 18 or later
- React Native 0.76 or later
- Expo apps
Because the SDK is pure JavaScript, iOS and Android version support follows your React Native version. No IDFA is collected, so AppTrackingTransparency (ATT) permission is not required on iOS.
Need Help?
Next Steps
- Client SDKs overview: pick the right SDK for each surface.
- Web SDK (JavaScript): for browser tracking, including
react-native-webapps. - iOS SDK, Android SDK, and Flutter SDK: if you build native or Flutter apps instead.
- Mobile app attribution: how app attribution works, and when you need a mobile measurement partner.
- Mobile Analytics: read app opens, sessions, screens, and tracked events in the dashboard.
How is this guide?

