React Native & Expo

Identify devices in a React Native or Expo app with @trace-id/sdk-react-native.

10 minutes

This quickstart adds Trace to a React Native app with @trace-id/sdk-react-native. You allow your app on a public key, wrap the app in a provider, identify the device before a sensitive action, and send the eventId to your backend for verification.

Before you start

You need a running Trace server and a public key (pk_...). The quick start guide covers both. The SDK works in Expo Go, in development builds and in bare React Native apps with Expo modules installed. It has no config plugin and no native code of its own.

  1. 1

    Install the SDK

    npx expo install picks the versions of the Expo modules that match your SDK:

    npx expo install @trace-id/sdk-react-native expo-application expo-crypto expo-device expo-localization expo-secure-store
  2. 2

    Allow your app on the key

    A native app sends no Origin header, so list the app itself among the key's allowed origins, next to your web origins: app: followed by the iOS bundle identifier or the Android application id.

    Text
    https://shop.example.com
    app:com.example.shop

    The SDK names its app in an X-Trace-App header. Like the web origin check, this decides which apps may use the key; it does not prove the request came from your app. That proof comes from verifying on your server (step 5).

  3. 3

    Add the provider

    TSX
    // App.tsx
    import { IdentifyProvider } from '@trace-id/sdk-react-native';
    
    export default function App() {
      return (
        <IdentifyProvider apiKey={process.env.EXPO_PUBLIC_TRACE_PUBLIC_KEY!} endpoint={process.env.EXPO_PUBLIC_TRACE_ENDPOINT!}>
          <RootNavigator />
        </IdentifyProvider>
      );
    }
    .env
    EXPO_PUBLIC_TRACE_PUBLIC_KEY=pk_...
    EXPO_PUBLIC_TRACE_ENDPOINT=https://id.example.com
  4. 4

    Identify before the action

    useVisitorData is the same hook as in the React SDK: { data, error, isLoading, getData }. With immediate: false nothing runs until you call getData.

    TSX
    // CheckoutScreen.tsx
    import { useVisitorData } from '@trace-id/sdk-react-native';
    
    export function CheckoutScreen({ order, user }: Props) {
      const { getData, isLoading } = useVisitorData({ immediate: false });
    
      async function pay() {
        const result = await getData({ linkedId: user.id, tags: { screen: 'checkout' } }); // null if Trace is unavailable
        await api.post('/orders/pay', { orderId: order.id, eventId: result?.eventId });
      }
    
      return <Button title="Pay" onPress={pay} disabled={isLoading} />;
    }

    getData never throws. On failure it resolves null and sets error, an IdentifyError with a code such as timeout, network or origin_not_allowed.

  5. 5

    Verify on your server

    Never act on what the app sends: on a rooted phone anything can be changed. Your backend fetches the event with a secret key, exactly as for the web:

    Events from apps carry an app object and two app signals:

    JSON
    {
      "visitorId": "…",
      "suspectScore": 30,
      "reasons": [{ "signal": "emulator", "contribution": 30 }],
      "app": { "platform": "android", "osVersion": "15", "manufacturer": "Google", "model": "sdk_gphone64_x86_64", "appId": "com.example.shop", "appVersion": "2.4.0", "buildVersion": "240", "isDevice": false, "rooted": false, "installedAt": 1763481600000 }
    }
    SignalWeightFires when
    emulator30The app runs on an emulator or simulator
    rootedDevice20Root (Android) or jailbreak (iOS) checks match

    The signals that do not depend on a browser apply too: VPN by time zone, Tor, datacenter and proxy IPs, velocity, accounts per device, flagged networks, replayed and tampered requests, and the fraud score.

How devices are recognised

  • Every launch: a visitor token kept in the Keychain or Keystore (expo-secure-store, this device only). On iOS it survives reinstalls.
  • After a reinstall that lost the token: the install id (identifierForVendor on iOS, ANDROID_ID on Android), hashed on the phone with your app id as salt. The raw id never leaves the device, and the same phone cannot be matched across different companies' apps.
  • Phones of the same model: they share every other reading, so two installs with different install ids are never merged.

No permission prompt appears. The SDK does not read location, contacts, the advertising id or the IMEI.

Not covered yet

Cloned apps, Frida and other hooking tools, factory resets, active calls, mocked GPS and on-device VPNs need native code beyond the Expo modules. They are on the roadmap for native iOS and Android SDKs.

Next steps

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.