# Set up the Hallway Test SDK in React Native or Expo

> Add the Hallway Test SDK to a React Native or Expo app in minutes: ask your coding agent to do it, or follow the manual steps for iOS and Android.

Page: https://hallwaytest.ai/mobile-app-recording/setup
Author: Oleksandr Haidaichuk, Technical specialist
Published: November 4, 2026. Last updated: November 4, 2026

**In short:** the fastest way is to ask your coding agent. With the Hallway Test MCP connected, say *Set up Hallway Test in this app*. The agent creates an app key, installs the SDK, wires it into your root component and asks before every native rebuild. This page lists the same steps for doing it by hand.

## Requirements

| | Requirement |
| --- | --- |
| React Native | 0.79 or newer, with the New Architecture (the default since 0.76) |
| Expo | SDK 53 or newer, in a development build. Expo Go cannot load the SDK |
| iOS | iOS 15.1 or newer, a real iPhone for video, a Mac with Xcode |
| Android | minSdk 24; screen recording needs Android 8.0 or newer |

## Set it up with your coding agent

1. Connect Hallway Test to [Claude](https://hallwaytest.ai/connect-mcp), [Cursor](https://hallwaytest.ai/connect-cursor) or [Codex](https://hallwaytest.ai/connect-codex).
2. Open your app's project and ask: *Set up Hallway Test in this app.*
3. The agent calls `setup_mobile_sdk`. It reads your package.json, router and Expo config, creates an app key, and gets back a plan with your key and the current SDK package link filled in.
4. It runs the install, edits your entry file, and asks you before `pod install` and native builds.
5. Record one session. Ask the agent to check: it calls `setup_mobile_sdk` again and confirms the upload arrived.

## Set it up by hand

1. **Create an app key.** Sign in at [mcp.hallwaytest.ai](https://mcp.hallwaytest.ai/app?view=apps), open **Mobile apps** and create a key. It looks like `ht_live_…`.
2. **Install the package.** The SDK is not on the npm registry yet; it installs from a package link Hallway Test gives you. Your agent's `setup_mobile_sdk` result contains the exact command, or write to [support@hallwaytest.ai](mailto:support@hallwaytest.ai) for the link.

   ```bash
   npm install @hallwaytest/react-native@<package link>
   ```

3. **Expo: add the config plugin** to app.json, then prebuild. The plugin adds the microphone permission text.

   ```json
   {
     "expo": {
       "plugins": ["@hallwaytest/react-native"]
     }
   }
   ```

   Bare React Native: run `cd ios && pod install` and add `NSMicrophoneUsageDescription` to Info.plist. Android needs no extra step.

4. **Configure the SDK** once, at the top of your root file (App.tsx, or app/_layout.tsx with expo-router), outside any component:

   ```tsx
   import { HallwayTest, HallwayTestButton, HallwayTestProvider } from '@hallwaytest/react-native';

   HallwayTest.configure({
     endpoint: 'https://mcp.hallwaytest.ai',
     appKey: 'YOUR_APP_KEY',
   });

   export default function App() {
     return (
       <HallwayTestProvider>
         {/* your app, as before */}
         <HallwayTestButton />
       </HallwayTestProvider>
     );
   }
   ```

5. **Rebuild and run on a device**: `npx expo run:ios --device` or `npx expo run:android` for Expo, `npx react-native run-android` or Xcode for bare apps.

## Record a session

1. Tap **Rec** in the app.
2. Allow the microphone the first time, and screen recording when asked. iOS asks on every start and records only your app.
3. Use the app as usual. The button can pause the session.
4. Tap **Stop**. The recording uploads on its own and shows up under the app in **Mobile apps**.

Besides the button, a session can start from code, from a shake of the device, or from a start link that opens your app.

## Next step

Open the recording, copy its link and ask your agent to audit it. What the audit contains is described in [how to audit a mobile app recording](https://hallwaytest.ai/learn/ai-ux-audit-mobile-app-recording). The first 10 recordings are free; see [mobile app recordings](https://hallwaytest.ai/mobile-app-recording).

[Create an app key](https://mcp.hallwaytest.ai/app?view=apps)

## FAQ

**There is no Rec button in the app**
The app was not rebuilt after the SDK was added, it is a release build where the SDK is off by default, or it runs in Expo Go, which cannot load native modules. Rebuild a debug build, or a development build for Expo.

**The recording has no video**
Screen capture was not allowed when the app asked. On iOS the app asks on every start, and the iOS Simulator never records video: use a real iPhone. On Android, screen recording needs Android 8.0 or newer.

**The recording has no sound**
The microphone permission was denied. Allow it in the phone's settings for the app. The SDK then records video with sound from the next session.

**The recording does not show up in the dashboard**
Check that the phone is online and that endpoint and appKey are copied exactly. Large videos upload in parts, so give it a minute; an interrupted upload resumes on its own, even after the app restarts.

**Shaking the phone opens the React Native developer menu**
That is React Native's own menu in debug builds and does not affect the SDK. The SDK's shake trigger is off by default and shows its own dialog when you turn it on.

**Can testers install the app from TestFlight?**
Yes, with a tester build. By default the SDK is linked into debug builds only. List your tester configuration in react-native.config.js to include it there, and keep it out of the build you publish to the App Store or Google Play.

## Related

- [Home](https://hallwaytest.ai/index.md)
- [Pricing](https://hallwaytest.ai/pricing.md)
- [Book a free pilot](https://hallwaytest.ai/book.md)