React Native & Expo

@metricraven/react-native records screen views, goals and identified users from your app. Events wait in a queue while the device is offline and are sent when it reconnects.

Set up

1. Allow your app in Settings

   In your site's Settings, add your bundle ID (iOS) or package name (Android) under Mobile apps, for example com.example.app. App events from IDs that aren't listed are rejected.

2. Install the SDK

   AsyncStorage is optional, but without it queued events are lost if the app is closed while offline.

   terminal

   Copy

   1

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

3. Create the client once

   analytics.ts

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   // analytics.ts
   import AsyncStorage from "@react-native-async-storage/async-storage";
   import * as Application from "expo-application";
   import { createMetricRaven } from "@metricraven/react-native";
   
   export const analytics = createMetricRaven({
     siteId: process.env.EXPO_PUBLIC_METRICRAVEN_SITE_ID!,
     appId: Application.applicationId ?? "com.example.app", // listed under Settings → Mobile apps
     appVersion: Application.nativeApplicationVersion ?? undefined,
     appBuild: Application.nativeBuildVersion ?? undefined,
     storage: AsyncStorage, // keeps the offline queue (and, with consent, the visitor ID)
     disabled: __DEV__,
   });

4. Track screens

   With Expo Router, track the route pattern from your root layout:

   app/_layout.tsx

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   14

   15

   16

   17

   18

   // app/_layout.tsx
   import { Slot, useSegments } from "expo-router";
   import { MetricRavenProvider, useExpoRouterTracking } from "@metricraven/react-native";
   import { analytics } from "../analytics";
   
   function ScreenTracking() {
     useExpoRouterTracking(useSegments()); // "/users/[id]", never the real ID
     return null;
   }
   
   export default function RootLayout() {
     return (
       <MetricRavenProvider client={analytics}>
         <ScreenTracking />
         <Slot />
       </MetricRavenProvider>
     );
   }

   With React Navigation, pass the helpers to your container. It records route names, not params:

   App.tsx

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   14

   15

   // App.tsx
   import { NavigationContainer, useNavigationContainerRef } from "@react-navigation/native";
   import { MetricRavenProvider, trackNavigation } from "@metricraven/react-native";
   import { analytics } from "./analytics";
   
   export default function App() {
     const navigationRef = useNavigationContainerRef();
     return (
       <MetricRavenProvider client={analytics}>
         <NavigationContainer ref={navigationRef} {...trackNavigation(analytics, navigationRef)}>
           {/* your navigators */}
         </NavigationContainer>
       </MetricRavenProvider>
     );
   }

5. Send events and identify users

   server.ts

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   analytics.track("cta_click", { source: "home" });
   analytics.screen("Paywall"); // a screen view outside your navigator
   analytics.identify(user.id, { name: user.name, email: user.email, plan: "pro" });
   analytics.reset(); // on logout
   analytics.setConsent(true); // from your consent prompt
   analytics.openedFromUrl(url); // utm_* from a deep link, for the next screen view
   
   // In components: const analytics = useMetricRaven(); useScreen("Settings");

Client

Consent and visitor IDs

The app follows the same rules as the website tracker. Until you call setConsent(true) (or pass consent: true), nothing that identifies the device is stored. The server derives a daily visitor ID from the network address and the app's user agent. Raw IP addresses are not kept. With consent, a random ID is kept in storage, so sessions on different days connect. Granting consent also relabels today's events from that device.

Offline queue and retries

Events are sent one at a time, in order. Network errors, timeouts, rate limits and server errors are retried with growing waits, up to 5 minutes, and Retry-After is respected. Rejected events are dropped instead of retried. That covers invalid data, an app ID that isn't listed, an unknown site, or paused tracking. Events replayed more than 5 minutes after they happened are recorded at the time they arrive.