React Native / Expo
Download 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.
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
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 in the matching environment. Configure RevenueCat or Superwall separately for financial metrics. Native AdServices collection is automatic only in the Swift SDK.