> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryproduck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native

> Add Produck's voice interviewer to an Expo or React Native app.

The React Native SDK, `@tryproduck/react-native`, puts the Produck duck in your app. A user taps
the duck, or accepts an offer from one of your campaign's triggers, and talks with the interviewer.
The interviewer reads the screen the user is on, points at what they mean and, if you allow it,
taps and types for them.

## Before you start

* **React Native 0.82 or later.** On an older version the SDK starts nothing and says so on the
  console.
* **A development build.** The SDK ships native code (WebRTC and audio), so it does not run in
  Expo Go. Build the app with `npx expo run:ios` or `npx expo run:android`, or with EAS.
* **Your SDK key**, from **Settings › SDK** in the [dashboard](https://tryproduck.com/app). It
  starts with `pk_live_`.

## Set up with one command

Run this in your app's folder, with your key:

```bash theme={null}
npx @tryproduck/wizard --key pk_live_YOUR_KEY
```

**Settings › SDK** shows this command with your key filled in. The wizard works in an Expo app and
in a React Native app without Expo. It shows every change and asks once before it makes any. Then it:

1. Installs your app's own packages first when they are not installed, from your lockfile without
   changing it (`npm ci`, `pnpm install --frozen-lockfile`, `yarn install --frozen-lockfile` or
   `--immutable`, `bun install --frozen-lockfile`), then the latest SDK and the native libraries
   your app lacks. It keeps a library your app already has. If one is older than the SDK supports,
   it stops before any change and names it, so you can upgrade it first. After the install it
   checks each version and tells you if one is still too old.
2. Adds the SDK's config plugin to `app.json` in an Expo app.
3. Adds the microphone and camera texts to `Info.plist` and the call permissions to
   `AndroidManifest.xml`, when the app has `ios/` or `android/` folders.
4. Wraps your app's root component in `withProduck`, with your key.
5. Lists the files it changed, and prints any step it could not do safely, for you to do by hand.

Then rebuild the app, and [check that it works](#check-that-it-works).

> [!TIP]
>
> Commit or stash your work before you run the wizard, so you can review its changes with
> `git diff`. The wizard warns you when the folder has uncommitted changes.

### Run it from a coding agent

A coding agent's shell has no terminal for the wizard to ask in. Add `--yes` to make the changes
without asking:

```bash theme={null}
npx @tryproduck/wizard --key pk_live_YOUR_KEY --yes
```

With `--yes` the wizard still lists the uncommitted files, every change and the steps left by hand.
It stops before any change when it finds no lockfile, or lockfiles of more than one package manager;
name the app's manager with `--package-manager npm`, `yarn`, `pnpm` or `bun` to go on. The AGENTS.md
block on **Settings › SDK** tells your agent to run it this way.

## Set up by hand

> [tab] Expo
>
> **1. Install the packages.** Let Expo pick the versions of these three:
>
> ```bash theme={null}
> npx expo install react-native-safe-area-context \
>   react-native-screens \
>   react-native-svg
> ```
>
> Install the rest with your package manager (npm, yarn, pnpm or bun), not with `npx expo install`.
> The SDK's config plugin sets them up, so Expo must not add their own plugins:
>
> ```bash theme={null}
> npm install @tryproduck/react-native \
>   react-native-audio-api \
>   react-native-get-random-values \
>   react-native-incall-manager \
>   react-native-webrtc
> ```
>
> **2. Add the config plugin** to `app.json`:
>
> ```json app.json theme={null}
> {
>   "expo": {
>     "plugins": ["@tryproduck/react-native"]
>   }
> }
> ```
>
> The plugin adds the microphone and camera texts on iOS, the call permissions on Android and
> the audio library's own setup. To use your own texts, pass them as options:
>
> ```json app.json theme={null}
> {
>   "expo": {
>     "plugins": [
>       [
>         "@tryproduck/react-native",
>         {
>           "microphonePermission": "Talk with our feedback interviewer.",
>           "cameraPermission": "This app never turns on your camera."
>         }
>       ]
>     ]
>   }
> }
> ```
>
> If your config is `app.config.js` or `app.config.ts`, add the same entry to its `plugins` list.
>
> **3. [Wrap your app](#wrap-your-app).**
>
> **4. Rebuild** with `npx expo run:ios` or `npx expo run:android`. The plugin changes native
> files, so a reload of the JavaScript is not enough.
>
> > [!NOTE]
> >
> > `npx expo run:ios` and `npx expo run:android` apply the plugin only when they create the
> > `ios/` or `android/` folder. If your app already has these folders, also make steps 2 to 6 of
> > the **React Native** tab.

> [tab] React Native
>
> **1. Install the packages:**
>
> ```bash theme={null}
> npm install @tryproduck/react-native \
>   react-native-audio-api \
>   react-native-get-random-values \
>   react-native-incall-manager \
>   react-native-webrtc \
>   react-native-safe-area-context \
>   react-native-screens \
>   react-native-svg
> ```
>
> **2. iOS: add the two texts** to `ios/<YourApp>/Info.plist`, inside the top `<dict>`:
>
> ```xml Info.plist theme={null}
> <key>NSMicrophoneUsageDescription</key>
> <string>Allow $(PRODUCT_NAME) to use your microphone when you talk with its feedback interviewer.</string>
> <key>NSCameraUsageDescription</key>
> <string>$(PRODUCT_NAME)'s feedback interviewer talks by voice only and never turns on your camera.</string>
> ```
>
> The interview never uses the camera. The WebRTC library contains code that asks for it, and
> App Store Connect refuses a build without a camera text (error ITMS-90683).
>
> **3. iOS: declare the privacy reason** in `NSPrivacyAccessedAPITypes` of your app's
> `PrivacyInfo.xcprivacy`, unless it is there:
>
> ```xml PrivacyInfo.xcprivacy theme={null}
> <dict>
>   <key>NSPrivacyAccessedAPIType</key>
>   <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
>   <key>NSPrivacyAccessedAPITypeReasons</key>
>   <array>
>     <string>35F9.1</string>
>   </array>
> </dict>
> ```
>
> **4. Android: add the permissions** to `android/app/src/main/AndroidManifest.xml`:
>
> ```xml AndroidManifest.xml theme={null}
> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
> <uses-permission android:name="android.permission.INTERNET" />
> <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
> <uses-permission android:name="android.permission.RECORD_AUDIO" />
> <uses-permission android:name="android.permission.WAKE_LOCK" />
> ```
>
> **5. Android: keep the release build working.** Add this line to
> `android/app/proguard-rules.pro`:
>
> ```text proguard-rules.pro theme={null}
> -dontwarn org.webrtc.Dav1dDecoder$Natives
> ```
>
> **6. Install the iOS pods:**
>
> ```bash theme={null}
> cd ios && pod install
> ```
>
> **7. [Wrap your app](#wrap-your-app)**, then rebuild with `npx react-native run-ios` or
> `npx react-native run-android`.

## Wrap your app

Wrap your root component once. Use `withProduck` on the default export:

```tsx App.tsx theme={null}
import { withProduck } from "@tryproduck/react-native";

function App() {
  return <YourApp />;
}

export default withProduck(App, { apiKey: "pk_live_YOUR_KEY" });
```

Or render `<ProduckProvider>` around your app. Both take the same options:

```tsx App.tsx theme={null}
import { ProduckProvider } from "@tryproduck/react-native";

export default function App() {
  return (
    <ProduckProvider apiKey="pk_live_YOUR_KEY">
      <YourApp />
    </ProduckProvider>
  );
}
```

With Expo Router, wrap the default export of `app/_layout.tsx` (or `src/app/_layout.tsx`).

## Check that it works

1. Start the development build on a phone or a simulator.
2. Find the duck in the bottom-right corner.
3. Tap the duck and allow the microphone.
4. Hold **Hold to talk** and say something. The interviewer answers through the loudspeaker.
5. Tap the stop button on the bar to end the call.

No duck? Look in the console for a line that starts with `Produck: not started`. It names the cause.
See [Troubleshooting](#troubleshooting).

## How an interview works

1. **It starts with a tap.** The user taps the duck, or accepts an offer that one of your triggers
   showed. The SDK asks for the microphone only then.
2. **The record bar opens at the bottom of the screen.** It shows the interviewer's current line above it. The user holds
   **Hold to talk** to speak, or opens the tools and types an answer. The microphone is open only
   while they hold the button.
3. **The interviewer reads the screen.** It knows the screen's buttons, fields and text by their
   names. It can point at an element with a ring and a label, and scroll to it.
4. **It can act, if you allow it.** With **Settings › Agent › Help level** set to **Acts**, the
   interviewer can tap a control or type into a field for the user. With **Shows**, it only points.
5. **The call ends** when the user taps the bar's stop button, when the app goes to the background, or
   when another app, such as a phone call, takes the sound for good.

> [!NOTE]
>
> An interview in a phone app keeps no recording of the screen or the sound, and files no ticket.
> During the call the SDK notes the user's taps, the screens they visited, the app's errors and its
> failed network requests, for the interviewer. It never notes the text the user typed.

## Tell Produck who the user is

Call `identify` from `useProduck()` once you know who the user is, for example right after
sign-in. Pass `null` to forget them, for example at sign-out:

```tsx theme={null}
import { useEffect } from "react";
import { useProduck } from "@tryproduck/react-native";

function useSignedInUser(user: User | null) {
  const produck = useProduck();
  useEffect(() => {
    produck.identify(user && { userId: user.id, email: user.email, name: user.name });
  }, [produck, user]);
}
```

| Field | Type | What it does |
| - | - | - |
| `userId` | string | Your id for the user. |
| `email` | string | The user's email. A private trigger is offered only to an email on your test accounts. |
| `name` | string | The user's name. |
| `traits` | object | Your own fields about the user: strings, numbers, booleans, `null`, lists of these, or one level of objects of these. |
| `languages` | string\[] | The languages the user speaks, as language tags such as `"en"` or `"ko"`, most preferred first. They pick the interview's language. |

An identity needs a `userId` or an `email`. If a value breaks a rule, the SDK keeps no identity and
logs one console error that names the field.

`useProduck()` works only inside the wrapped app. Outside it, it throws.

## Offer an interview at the right moment

A campaign's triggers offer its interview. Each trigger on the campaign's **Triggers** tab has an
id. When the moment it describes happens in your app, fire it:

```tsx theme={null}
const produck = useProduck();
produck.fire("TRIGGER_ID");
```

The SDK shows an offer with the trigger's words, or "Got a minute to tell us how that went?". When
the user accepts, the interview starts under that trigger.

* A trigger offers at most once per run of the app. Pass `{ repeat: true }` to offer it again:
  `produck.fire("TRIGGER_ID", { repeat: true })`.
* A fire shows nothing, and says why on the console, when the trigger is not active, another offer
  is showing, or an interview is already running. A fire during an interview does not count, so
  the trigger can still offer after the call.

### Fire triggers from PostHog events

A trigger can fire on a PostHog event instead of a call. Set **Fires on** to **PostHog trigger** on
the campaign's **Triggers** tab, and pass your `posthog-react-native` client to the SDK:

```tsx App.tsx theme={null}
import { PostHog } from "posthog-react-native";
import { ProduckProvider } from "@tryproduck/react-native";

const posthog = new PostHog("phc_YOUR_POSTHOG_KEY", { host: "https://us.i.posthog.com" });

export default function App() {
  return (
    <ProduckProvider apiKey="pk_live_YOUR_KEY" posthog={posthog}>
      <YourApp />
    </ProduckProvider>
  );
}
```

The SDK then fires a trigger whenever your app captures its event and the trigger's filters pass.
If you use `<PostHogProvider>`, give it the same client with its `client` prop, so both read one
PostHog.

## Keep parts of the screen private

Wrap anything the interviewer must not read in `<ProduckMask>`. It adds no view, so your layout
does not change:

```tsx theme={null}
import { ProduckMask } from "@tryproduck/react-native";

<ProduckMask>
  <AccountBalance />
</ProduckMask>;
```

The interviewer does not see, point at or touch anything inside a mask. Some fields it never types
into, masked or not:

* password fields (`secureTextEntry`);
* one-time-code and payment-card fields;
* fields whose `testID` or `nativeID` names a secret, such as `card-number`.

The interviewer also never sees text the user typed into a field.

## Place the duck

Pass `launcher` to choose where the duck sits:

```tsx theme={null}
<ProduckProvider apiKey="pk_live_YOUR_KEY" launcher={{ corner: "bottom-left", bottomOffset: 49 }}>
```

| Option | Values | Default |
| - | - | - |
| `corner` | `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"` | `"bottom-right"` |
| `bottomOffset` | The height in points of a band you keep at the bottom, such as a tab bar. The duck sits above it. | `0` |
| `draggable` | `true` lets the user drag the duck; it stays on screen. | `false` |

## Match the offer to your app

Pass `theme` to give the offer your colours, corners and font. Every option is optional; an
option you leave out keeps Produck's look:

```tsx theme={null}
<ProduckProvider
  apiKey="pk_live_YOUR_KEY"
  theme={{ surface: "#101418", ink: "#F5F7FA", acceptSurface: "#3B82F6", radius: 16 }}
>
```

| Option | What it sets |
| - | - |
| `surface` | The offer's background colour. |
| `ink` | The text colour. |
| `line` | The border colour. |
| `radius` | The offer's corner radius, in points. |
| `shadow` | The offer's shadow, written as a CSS box shadow. |
| `fontFamily` | The font. |
| `focus` | The outline of a control focused from a keyboard. |
| `buttonRadius` | The buttons' corner radius, in points. |
| `acceptSurface` | The accept button's background colour. |
| `acceptInk` | The accept button's text colour. |
| `declineInk` | The decline button's text colour. |
| `hover` | The decline button's background while it is pressed. |

## Options

`withProduck(App, options)` and `<ProduckProvider>` take these options:

| Option | Required | What it does |
| - | - | - |
| `apiKey` | yes | Your SDK key, from **Settings › SDK**. |
| `posthog` | no | Your `posthog-react-native` client, for triggers that fire on PostHog events. |
| `launcher` | no | Where the duck sits. See [Place the duck](#place-the-duck). |
| `theme` | no | The offer's look. See [Match the offer to your app](#match-the-offer-to-your-app). |
| `apiBase` | no | The API the SDK talks to. Leave it unset to use Produck's. |

## Troubleshooting

| Console line | What to do |
| - | - |
| `Produck: not started — Expo Go cannot load the SDK's native libraries; run a development build.` | Build the app with `npx expo run:ios`, `npx expo run:android` or EAS, and open that build. |
| `Produck: not started — React Native 0.xx is older than 0.82, the SDK's minimum.` | Upgrade React Native to 0.82 or later. |
| `Produck: fire ignored — …` | The line says why the trigger showed no offer, for example `trigger "…" is not active`. |
| `Produck: identify refused — …` | The line names the field that broke a rule. Fix the value and call `identify` again. |

If the bar says **Your interviewer couldn't connect. Try again.**, check the network and that the
key in `apiKey` is a live key from **Settings › SDK**. If the bar says **This interview needs your
microphone.**, the user refused the microphone. On iOS they can allow it again in the Settings app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.