# React Native

> Pin feedback on the real screen in iOS and Android apps.

Source: https://docs.usejot.co/docs/install/react-native

Jot for React Native is the same product as the web widget: a reviewer taps the
broken thing on a real screen and types one sentence. Your team gets the screen,
the element, a masked screenshot, the device and the build. They can also get a
recording with video, console, network and crashes.

It runs on iOS and Android, needs React Native 0.80 or newer with the New
Architecture, and Android 7 (API 24) or newer. Expo works with a development
build. Expo Go does not, because Jot has native code.

## Install

One package. Nothing else to add: Jot brings its own storage, safe-area and
icon drawing.

<Tabs items={["Expo", "Bare React Native"]}>
  <Tab value="Expo">
    ```bash
    npx expo install @usejot/react-native
    ```

    This also adds `"@usejot/react-native"` to the `plugins` in your `app.json`.
    The plugin lets iOS finish uploading a recording after the reviewer leaves the
    app. If your config is `app.config.js`, add it there yourself:

    ```js title="app.config.js"
    export default {
      plugins: ["@usejot/react-native"],
    };
    ```

    Then rebuild your development build (`npx expo prebuild`, or your EAS build).
  </Tab>

  <Tab value="Bare React Native">
    ```bash
    npm install @usejot/react-native
    npx pod-install
    ```

    Android needs nothing more. On iOS, so a recording finishes uploading after
    the reviewer leaves the app, forward background sessions from your AppDelegate:

    ```swift title="ios/YourApp/AppDelegate.swift"
    import JotReactNative

    func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String,
                     completionHandler: @escaping () -> Void) {
      _ = RNJotKitBridge.handleBackgroundUploadEvents(identifier, completion: completionHandler)
    }
    ```
  </Tab>
</Tabs>

## Wrap your app

```tsx title="App.tsx"
import { NavigationContainer, useNavigationContainerRef } from "@react-navigation/native";
import { JotProvider } from "@usejot/react-native";

export default function App() {
  const navigationRef = useNavigationContainerRef();
  return (
    <JotProvider projectKey="jot_pk_your_key" navigationRef={navigationRef}>
      <NavigationContainer ref={navigationRef}>{/* your screens */}</NavigationContainer>
    </JotProvider>
  );
}
```

The provider adds a small floating button. Tap it and Jot opens. Nothing else
in your app changes.

## Screens

`navigationRef` takes React Navigation's container ref. Jot reads the current
route's name and listens for changes, so every Jot is filed under the screen it
was made on, such as "Checkout". Pins, presence and recordings follow the
screen. Without it, the whole app counts as one screen.

## Props

| Prop            | What it does                                                                                                                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectKey`    | Required. Your project's public widget key                                                                                                                                                                    |
| `environment`   | `"staging"`, `"preview-142"`. Filters in the dashboard                                                                                                                                                        |
| `navigationRef` | Screen names for pins, presence and recordings                                                                                                                                                                |
| `trigger`       | `"fab"` (default) or `"tab"`                                                                                                                                                                                  |
| `position`      | Where it sits. Button: `"bottom-right"` (default), `"bottom-left"`, `"bottom"`, `"top-left"`, `"top"`, `"top-right"`. Tab: `"right"` (default), `"left"`, or along the top or bottom (`"top"`, `"top-left"`…) |
| `label`         | The tab's text and the trigger's accessible name, up to 24 characters. Default "Feedback"                                                                                                                     |
| `icon`          | `"jot"` (default), `"chat"`, `"bug"` or `"none"` (the tab's default)                                                                                                                                          |
| `offset`        | A side tab's position, 0–100 (percent of the height). Default 50                                                                                                                                              |
| `edge`          | Deprecated: use `position`                                                                                                                                                                                    |
| `autostart`     | `false` waits for `useJot().init()`, for example after consent                                                                                                                                                |
| `authScheme`    | Optional, and most apps never set it. Only for **Continue with Google**, and only to replace the default redirect scheme `jot.<your bundle id>`. See [Sign-in](#sign-in)                                      |

## Open Jot from your own UI

```tsx
import { useJot } from "@usejot/react-native";

function HelpMenu() {
  const jot = useJot();
  return <Button title="Report a problem" onPress={jot.open} />;
}
```

`useJot()` returns `open`, `close`, `startRecording`, `init` and `isOpen`.
Outside a `JotProvider` it does nothing.

## Pins land on the same element

When a reviewer taps, Jot finds the view under their finger. It records what
that view is: its accessibility label, its text, its place in the view tree and
its `testID`. Later, on another phone, a tablet or in landscape, Jot finds the
same view and puts the pin at the same spot inside it. You don't have to set
anything up.

For the elements that matter most, add an exact ID:

```tsx
import { JotAnchor } from "@usejot/react-native";

<JotAnchor id="checkout.pay">
  <Pressable onPress={pay}>
    <Text>Pay now</Text>
  </Pressable>
</JotAnchor>;
```

`JotAnchor` puts the ID on its child as `testID` and `nativeID`, so your layout
stays the same. A custom component must pass both on to a native view.
If no view on the screen matches a pin, the pin is shown at the spot it was
dropped, marked approximate. If its element has left the screen, the pin hides.

## Privacy

Masking happens on the device, before an image or a recording exists.

* Password fields (`secureTextEntry`) are always blacked out.
* Wrap anything else in `JotMask`:

```tsx
import { JotMask } from "@usejot/react-native";

<JotMask>
  <Text>{customer.cardNumber}</Text>
</JotMask>;
```

* To mask without shipping a build, add ids under **Project → Settings →
  Masked element ids (native apps)**. Any `JotAnchor` with that id, and any
  `<JotMask id="…">` with it, is blacked out.

Recorded network calls keep their method, URL, status and timing. Credential
headers, secret query parameters and secret body fields such as `password`,
`token` and `cardNumber` are replaced on the device. Bodies are kept only when
**Capture request and response bodies** is on in **Project → Settings →
Recording privacy**. Keystrokes are never recorded. Only tap positions are.

## Recording

A reviewer taps **Record**, shows the problem, then taps **Stop & describe**.
The last two minutes of the app's own window are encoded to video natively, on
a background thread. That recording goes with the Jot, along with the console,
network calls, screen changes, taps and app lifecycle. Nothing is uploaded until
the Jot is sent.

Console output is captured on its own. So are calls made with `fetch`, axios or
anything else built on `XMLHttpRequest`. For a client that bypasses it, such as
`expo/fetch`, wrap the client:

```ts
import { fetch as expoFetch } from "expo/fetch";
import { JotHttp } from "@usejot/react-native";

export const fetch = JotHttp.wrap(expoFetch);
```

For a native HTTP module you can't wrap, report each call yourself with
`JotHttp.record({ method, url, status, durationMs })`. It is redacted like the
rest.

## Crashes

If the app crashes, Jot saves the error before the app closes. A JavaScript
error and a native crash are handled the same way. On the next launch, Jot asks
the reviewer whether to send it to the team. If they agree, the crash becomes a
**Bug** Jot on the screen it happened on, with the stack trace and whatever was
recorded.

Jot runs its own crash handler first, then hands the crash on to whatever
handler your app already had, such as Crashlytics or Sentry.

## Sign-in

Invited reviewers sign in with a 6-digit code sent to their email. That needs
no setup.

To offer **Continue with Google** too, add your redirect scheme under
**Project → Settings → App redirect schemes**. By default it is `jot.` plus your
bundle ID (iOS) or package name (Android), lowercased, with any `_` turned into
`-`: `jot.com.acme.shop`. If the two ids differ, add both schemes. The default
needs no setup on either platform.

`authScheme` is optional. Email-code sign-in and anonymous feedback never need it,
and Google sign-in works with the default scheme. Only to choose another scheme,
pass `authScheme` to `JotProvider`, and register it for the build:

* **Expo** — pass it to the plugin too:

  ```json title="app.json"
  {
    "expo": {
      "plugins": [["@usejot/react-native", { "authScheme": "shop.acme" }]]
    }
  }
  ```

  The plugin adds the scheme to iOS's `Info.plist` and to the Android build.

* **Bare** — set it on Android, which declares the scheme at build time. iOS
  needs nothing.

  ```groovy title="android/app/build.gradle"
  android {
    defaultConfig {
      manifestPlaceholders["jotAuthScheme"] = "shop.acme"
    }
  }
  ```

## Allow your app

In **Project → Settings → Allowed apps**, add your bundle ID (iOS) and your
package name (Android), for example `com.acme.shop`. A project with no allowed
apps accepts every app. The app settings appear on React Native and Flutter
projects.

Like an allowed domain, an app ID can be spoofed. It is a convenience gate, not
a password. The reviewer's sign-in is what protects your feedback.

## Phones and tablets

On screens narrower than 640 points, Jot opens as a bottom sheet that you can
drag between two heights. On wider screens, it opens as a card beside the pin.
Both work in portrait and landscape, and the sheet moves up when the keyboard
opens.
