Install the mobile SDK

@datacub/react-native is for React Native and Expo apps. Its logic is fully tested; runs on real Android and iOS simulators in CI are still being brought up. No runtime dependencies, about 5 KB with gzip.

Install

Not published yet: @datacub/react-native is not on npm, and nothing under @datacub on npm belongs to datacub, so do not install it from there. Contact the datacub team for early access.

The SDK works with these, which you install as usual:

npx expo install @react-native-async-storage/async-storage expo-application

expo-application is optional in bare apps: pass your own app values instead (below).

Start it

App.tsx
import AsyncStorage from '@react-native-async-storage/async-storage'
import * as Application from 'expo-application'
import datacub from '@datacub/react-native'

datacub.init('pk_live_YOUR_PROJECT_KEY', { storage: AsyncStorage, app: Application })

Then add your app's bundle ID (iOS) or package name (Android), such as sa.example.shop, to the apps allowed to send in Settings, General. Events from an app that is not on the list are refused. pk_test_ keys also accept Expo Go while you develop.

Options

OptionWhat it does
storagewhere IDs and unsent events live between launches: AsyncStorage, or anything with getItem, setItem, removeItem (sync or async, so an MMKV wrapper works). Without it every launch is a new Guest and unsent events are lost when the app closes
app{ applicationId, nativeApplicationVersion?, nativeBuildVersion? }. expo-application already has that shape
apiHostyour ingestion host or proxy. Default https://ingest.datacub.example

In a bare app without expo-application:

import AsyncStorage from '@react-native-async-storage/async-storage'
import datacub from '@datacub/react-native'

datacub.init('pk_live_YOUR_PROJECT_KEY', {
  storage: AsyncStorage,
  app: { applicationId: 'sa.example.shop', nativeApplicationVersion: '2.3.0', nativeBuildVersion: '87' },
})

Screens

Screens are the app's page views. Send the screen's name or route template, never values from it.

App.tsx
import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native'
import { trackNavigation } from '@datacub/react-native/navigation'

export default function App() {
  const ref = useNavigationContainerRef()
  return (
    <NavigationContainer ref={ref} onReady={() => trackNavigation(ref)}>
      {/* your navigators */}
    </NavigationContainer>
  )
}

The same name twice in a row counts once. Segments that look like IDs, emails or numbers are replaced (Product/4512 becomes Product/:id).

What it does on its own

  • Sessions: 30 minutes idle, 24 hours at most, kept across restarts.
  • Delivery: batches every 10 seconds or at 20 events, and when the app goes to the background. Retries with backoff when offline. Up to 1,000 events wait on the device.
  • No lifecycle events: opening and backgrounding the app send nothing, so they never inflate your active users.
  • Never sent: advertising IDs, device IDs, device model, carrier, location, contacts, screen size or time zone.

Call await datacub.flush() to send what is queued now, for example before a test ends.

Android backup

Android Auto Backup restores app data on a new phone, so a restored install keeps its Guest ID. That is usually the same person. To give every install its own ID, set android.allowBackup: false in Expo, or exclude AsyncStorage's database (RKStorage) in dataExtractionRules in a bare app.