# React Native / Expo

Download [Submetry.mjs](https://submetry.com/sdk/Submetry.mjs) into your app, for example `src/telemetry/Submetry.mjs`. This is a source adapter, with no published npm package. It uses your existing persistent storage and fetch; no additional native telemetry dependency is required.

## Configure once

Pass a persistent storage object with asynchronous `getItem(key)` and `setItem(key, value)` methods. Your existing AsyncStorage instance satisfies that interface. Do not configure from a screen render or a replayed React effect.

```js
import { AppState, Platform } from 'react-native';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { createSubmetry } from './telemetry/Submetry.mjs';

// Configure your financial SDK first; use its real app-user identity if installed.
export const telemetry = await createSubmetry({
  appId: 'YOUR_APP_ID',
  key: 'YOUR_PUBLIC_SUB_PK_KEY',
  storage: AsyncStorage,
  userId: actualAppUserId,
  context: { platform: Platform.OS, environment: __DEV__ ? 'debug' : 'production' },
  onError: message => console.warn(message),
});
AppState.addEventListener('change', state => {
  if (state === 'active') void telemetry.startSession();
  else void telemetry.flush();
});
```

If your AsyncStorage version exposes `createAsyncStorage`, pass the storage instance returned by it. Retain your app’s existing storage version. Expo projects can pass their current persistent storage adapter rather than adding an unrelated native package.

## Record real actions

```js
await telemetry.onboardingStep(1, 'goal');
await telemetry.onboardingCompleted();
await telemetry.track('activation_completed');
await telemetry.paywallShown('onboarding');
await telemetry.track('generation_completed', { style: 'kinetic' });
// Only after confirmed purchase completion:
await telemetry.track('purchase_completed', { plan: 'monthly' });
await telemetry.identify(newFinancialProviderUserId);
```

The adapter persists an anonymous installation ID, first-open marker and every event before delivery. It emits `first_open` once and `session_start` / `app_open` at configuration. Call `startSession()` on subsequent foreground transitions. Context can include version, build, OS, device model, locale and timezone as short strings. Set known TestFlight builds explicitly.

## Retry and verification

Batches contain up to 20 events with stable IDs. Temporary failures retain the queue across restarts and use exponential delay up to five minutes, with at most eight consecutive automatic attempts. Manual `flush()` or a new launch resumes delivery. Permanent schema rejection is archived under the storage key suffixed `:rejected`; inspect before replaying. Call `stop()` when retiring an instance, and keep only one active instance per app/storage key.

JavaScript tests verify persistence, stable retry IDs, concurrent recording during upload, queue corruption protection and rejected-batch archiving. Native React Native/Expo builds and device background behavior still require validation in your app. Verify response 202 and [Events](https://submetry.com/app/events) in the matching environment. Configure [RevenueCat](https://submetry.com/docs/revenuecat.md) or [Superwall](https://submetry.com/docs/superwall.md) separately for financial metrics. Native AdServices collection is automatic only in the Swift SDK.
