Book free pilot
Book free pilot

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.

Create an app key What gets recorded
  • Expo and bare React Native
  • iOS 15.1+ and Android 8.0+
  • Off in release builds by default

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, Cursor or 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, 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 for the link.

    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.

    {
  "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:

    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. The first 10 recordings are free; see mobile app recordings.

Questions, answered

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.

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 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.

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.

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.

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.

Create an app key

Written by Oleksandr Haidaichuk, Technical specialist · Published November 4, 2026 · Last updated · Markdown version