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

# React Native

> Add the Cr3dentials SDK to a React Native or Expo app and get your first test webhook in under 30 minutes.

`@cr3dentials/zktls-react-native` is a thin bridge over the native [iOS](https://docs.cr3dentials.xyz/sdk/ios.md) and [Android](https://docs.cr3dentials.xyz/sdk/android.md) SDKs: the native SDK does the work, and JavaScript drives it through one API on both platforms. This page takes you from an empty project to your first test webhook, with your test key and the demo platform `zktls-demo`, so you need no real account anywhere.

## Before you start

* Your **test key** (`zk_test_…`) from [Register your app](https://docs.cr3dentials.xyz/sdk/overview.md#register-your-app).
* A **webhook endpoint** that checks the signature, and its signing secret. [Webhooks](https://docs.cr3dentials.xyz/essentials/webhooks.md) has the code for Node and Python.
* React Native 0.80 or later, with the New Architecture: the bridge is a Turbo Module.
* iOS 14.0 or later, and Android 7.0 (API 24) or later, as the native SDKs require.

## 1. Install

```sh theme={null}
npm install @cr3dentials/zktls-react-native
```

Android needs nothing more: Gradle fetches the SDK from Maven Central. On iOS, the SDK's releases repository is its own CocoaPods spec source. Keep it first in your `Podfile`, because CocoaPods takes a pod from the first source that has it, then run `pod install`:

```ruby theme={null}
source 'https://github.com/Cr3dentials/zktls-sdk-releases.git'
source 'https://cdn.cocoapods.org/'
```

### Expo

The package's config plugin writes those two sources into the Podfile, so `expo prebuild` can regenerate it. Add the plugin to `app.json` (or `app.config.js`), then prebuild:

```json theme={null}
{
  "expo": {
    "plugins": ["@cr3dentials/zktls-react-native"]
  }
}
```

```sh theme={null}
npx expo prebuild
```

The bridge is a native module, so it runs in a development build, not in Expo Go.

## 2. Configure

Call `Zktls.configure` once, when your app starts:

```ts theme={null}
import { Zktls } from '@cr3dentials/zktls-react-native';

await Zktls.configure('zk_test_…');
```

The app key is publishable, so it can live in your code or your build config. Use the test key in development builds and the live key in release builds.

## 3. Verify

`Zktls.verify` takes the platform ids and your `reference`, and resolves when the user leaves the flow:

```ts theme={null}
import { Zktls, type ZktlsError } from '@cr3dentials/zktls-react-native';

const orderId = 'order_8f3k2'; // yours: a value your server already knows

try {
  const outcome = await Zktls.verify(['zktls-demo'], orderId);
  for (const p of outcome.platforms) {
    // p.status: 'done' (the result is on its way to your server), 'failed' (p.reason says why,
    // for your logs) or 'notStarted' (the user didn't run it: offer to finish later)
  }
} catch (e) {
  const err = e as ZktlsError;
  if (err.code === 'Refused') {
    // The verification did not start. The SDK has already told the user why.
    console.warn('refused', err.refusal, err.message); // see Errors
  }
}
```

The outcome tells your app only how each platform ended. The results go to your server, by webhook. Don't wait in the app for them: show your own next step as soon as `verify` resolves. The fields are in [The outcome](https://docs.cr3dentials.xyz/sdk/overview.md#the-outcome), and the refusal codes are in [Errors](https://docs.cr3dentials.xyz/sdk/errors.md).

**To finish later**, call `verify` again with the platforms that were not started. It is a new verification, and you can pass the same reference.

**To start from your server**, have your server create a token with [`POST /partner/verification-tokens`](https://docs.cr3dentials.xyz/api-reference/verifications#create-a-verification-token) and pass it to the app:

```ts theme={null}
const outcome = await Zktls.verifyToken(token); // token: "vt_…", from your server
```

## 4. Test with `zktls-demo`

**1. Run your app**

Run a development build on a simulator, an emulator or a phone, with your test key, and tap the button that calls `Zktls.verify(['zktls-demo'], reference)`.

**2. Choose the demo platform**

Tap it on the platform list. On its consent screen, tick both boxes and tap **Continue to verification**.

**3. Sign in to the demo bank**

Enter any user name and the password `demo`, which the page shows.

**4. See the outcome**

The SDK hands the run to an attester, and the list shows the platform as **Verified**. Tap **Done**: `verify` resolves with `zktls-demo` as `'done'`.

**5. Get the webhooks**

Within seconds, your endpoint receives a `platform.finished` with `"test": true` and the demo bank's latest transfer, and a `verification.finished`, in either order. Both carry your `reference`.

## 5. Theme and strings

`configure` also takes a theme and the screens' words:

```ts theme={null}
await Zktls.configure(
  'zk_test_…',
  { accent: '#1E66F5', background: '#FFFFFF', text: '#111111', logo: 'brand_logo' },
  { 'list.title': 'Verify your income' },
);
```

Colours are exactly `#RRGGBB` or `#AARRGGBB` (alpha first). `logo` names an image in your app: an Android drawable and an iOS asset of that name. A field you leave out keeps the SDK's default. The platform list and the consent screens are in Cr3dentials' colours, with your logo at the top; your colours apply to the refusal screen.

The string keys are the native SDK's, the same on both platforms: see the table on the [iOS](https://docs.cr3dentials.xyz/sdk/ios.md#5-theme-and-strings) or [Android](https://docs.cr3dentials.xyz/sdk/android.md#5-theme-and-strings) page. Keep the words in braces, which the SDK fills in.

A colour in another form, or a value in `strings` that isn't a string, rejects `configure` with the code `InvalidArgument` and a message naming it, such as `theme.accent must be #RRGGBB or #AARRGGBB`. The SDK's configuration is then left as it was.

## Things to know

* **The screens.** On Android, `verify` shows them over the current activity, which must stay in front until it resolves. On iOS, over the key window's top-most view controller.
* **One verification at a time.** A `verify` called while another runs waits for it to finish.
* **Reloads.** When the module goes away, as on a JavaScript reload, a `verify` in flight ends: the SDK takes its screens down and the promise rejects with `Cancelled`.
* **Errors.** A failed call rejects with an `Error` whose `code` is the SDK's error name, as listed in [Errors](https://docs.cr3dentials.xyz/sdk/errors.md). For `Refused`, `refusal` holds the reason, such as `device_not_verified`. `InvalidArgument` is the bridge's own. `Internal` is a fault inside the SDK: report it to us.
* **The notification.** On Android, the SDK's foreground service shows a notification reading "Verifying". To translate or rebrand it, define `zktls_session_notification_title`, `zktls_session_channel_name` and the drawable `zktls_session_notification_icon` in your app's resources.
* **Logging.** Log the `verificationId`, the statuses, the reasons and the refusal codes. Your Partner API key and webhook secret never belong in the app at all.

## Before you submit

The native requirements apply to your app: App Attest on iOS and Play Integrity on Android for live keys, your registered bundle ID and package name, and the privacy answers. See **Before you submit** on the [iOS](https://docs.cr3dentials.xyz/sdk/ios.md#before-you-submit) and [Android](https://docs.cr3dentials.xyz/sdk/android.md#before-you-submit) pages, then work through the [release checklist](https://docs.cr3dentials.xyz/sdk/release-checklist.md).

Version 2 of the bridge wraps version 2 of the SDK: it depends on 2.2.0 or later, within 2.x. The package is on npm: [@cr3dentials/zktls-react-native](https://www.npmjs.com/package/@cr3dentials/zktls-react-native).


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