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-nativeis not on npm, and nothing under@datacubon 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-applicationexpo-application is optional in bare apps: pass your own app values instead (below).
Start it
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
| Option | What it does |
|---|---|
storage | where 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 |
apiHost | your 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.
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>
)
}import { Slot, useSegments } from 'expo-router'
import { useEffect } from 'react'
import datacub from '@datacub/react-native'
export default function RootLayout() {
const segments = useSegments()
// the route template (/profile/[user]), never the path with values (/profile/sara)
useEffect(() => datacub.screen(segments.join('/') || 'index'), [segments])
return <Slot />
}import datacub from '@datacub/react-native'
datacub.screen('Checkout')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.