React Native Setup

Use this guide for a bare React Native app. Expo apps should use the dedicated Expo development-build guide.

1. Add the package

Install the JavaScript package from npm, install iOS pods, and rebuild the native app:

npm install @ansight/react-native
npx pod-install

Platform requirements

• React Native 0.72 or newer.
• Android API 23 or newer with a Java 17-compatible Android build toolchain.
• iOS/iPadOS deployment target 15.0 or newer.

The package uses React Native autolinking. See React Native Packages for the native iOS and Android dependencies resolved by the bridge.

2. Initialize the development build

Initialize Ansight once from JavaScript app bootstrap. Put the helper below in a startup module called from index.js or index.ts before AppRegistry.registerComponent(...), or call it from a guarded useEffect(...) in the root App.tsx / App.jsx if setup depends on React-provided configuration. Do not put initialization in a screen component that can mount repeatedly.

For a normal React Native app, do not manually edit native MainApplication, MainActivity, or iOS AppDelegate just to install the bridge; autolinking handles the native package wiring. Use native files only for app-owned native tools or custom pairing UI after the bridge has initialized.

TypeScript

import Ansight from "@ansight/react-native";

let ansightStarted = false;

export async function startAnsight() {
  if (!__DEV__ || ansightStarted) {
    return;
  }
  ansightStarted = true;

  await Ansight.initializeAndActivate({
    useNativeAllInOneDefaults: true,
    clientName: "React Native App",
    toolGuard: "readOnly",
  });
}

JavaScript

import Ansight from "@ansight/react-native";

let ansightStarted = false;

export async function startAnsight() {
  if (!__DEV__ || ansightStarted) {
    return;
  }
  ansightStarted = true;

  await Ansight.initializeAndActivate({
    useNativeAllInOneDefaults: true,
    clientName: "React Native App",
    toolGuard: "readOnly",
  });
}

Call void startAnsight(); from index.ts / index.js, or call it once from the root App component’s useEffect(...) if your setup needs React-provided configuration.

Use the app’s explicit internal-build flag instead of __DEV__ when that is the approved Ansight variant. Use a separate development target when the native package must be absent from distributable builds.

3. Add stable test ids

Give important controls stable testID values so live and recorded React trees remain easy for developers and agents to query:

<Pressable testID="login-button" onPress={signIn}>
  <Text>Sign in</Text>
</Pressable>

4. Run and verify

Start the host in one terminal:

ansight host run

Launch one native development build:

npx react-native run-ios
# or: npx react-native run-android

After the app is running, confirm its session and tool catalog from another terminal:

ansight session list --connected --json
ansight app tools <session-id> --detail summary --include-unavailable --max-results 50 --json

A physical device requires the one-time enrollment flow.

Important: Enabling native all-in-one defaults enables session JPEG capture. Screen capture will result in an FPS drop while frames are captured, encoded, and transported. Disable sessionJpegCapture for trend-focused runs unless visual evidence is required.

Do not ship enrollment UI or broad remote-tool access in App Store, Play Store, CI release, or other distributable builds.

Troubleshooting

• The native module is missing: rerun npx pod-install on iOS, clean the Android build when needed, rebuild the native app, and restart Metro.
• The app is an Expo project: use the dedicated Expo development-build guide; Expo Go cannot load the bridge.
• No connected session: confirm the host is running and startAnsight() is called once while __DEV__ or the approved internal-build flag is true.