> For the complete documentation index, see [llms.txt](https://docs.voveid.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voveid.com/docs/sdks/react-native.md).

# React Native SDK

Integrate VOVE ID in a React Native application and handle typed journey results.

The SDK supports React Native applications on iOS and Android. Use the package version your team has tested and approved.

## Install

```bash
npm install @vove-id/react-native-sdk
cd ios && pod install
```

For iOS, add `NSCameraUsageDescription`. For Android, add `android.permission.CAMERA`. Request permission at runtime on both platforms before starting.

## Initialize

```typescript
import {
  initialize,
  VoveEnvironment,
} from '@vove-id/react-native-sdk';

await initialize({
  environment: VoveEnvironment.Sandbox,
  publicKey: 'public_sandbox_replace_me',
});
```

Initialize before `start()`. The public key may ship in the app; the private `x-api-key` must stay on your backend.

## Start

```typescript
import {
  start,
  VoveEnvironment,
  VoveLocale,
  VoveStatus,
} from '@vove-id/react-native-sdk';

const result = await start({
  environment: VoveEnvironment.Sandbox,
  sessionToken: tokenFromYourBackend,
  showUI: true,
  exitAfterEachStep: false,
  enableVocalGuidance: false,
  locale: VoveLocale.EN,
});

switch (result.status) {
  case VoveStatus.Success:
    showAwaitingServerConfirmation();
    break;
  case VoveStatus.Pending:
    showPendingReview();
    break;
  case VoveStatus.Failure:
    showVerificationFailed();
    break;
  case VoveStatus.Canceled:
    showVerificationCanceled();
    break;
  case VoveStatus.MaxAttempts:
    showSupportOptions();
    break;
}
```

Do not authorize the user directly from `Success`. Confirm the current resource on your backend after a verified webhook.

## Types and values

```typescript
interface VoveVerificationResult {
  status: VoveStatus;
  nextStep?: VoveVerificationStep;
}

interface VoveStartConfig {
  environment: VoveEnvironment;
  sessionToken: string;
  enableVocalGuidance?: boolean;
  locale?: VoveLocale;
  showUI?: boolean;
  exitAfterEachStep?: boolean;
}
```

Documented result values are `success`, `pending`, `cancelled`, `failure`, and `max-attempts`. Documented next steps are `LIVENESS`, `ID_DOCUMENT`, `DRIVING_LICENSE`, `ADDRESS_PROOF`, `CAR_REGISTRATION_CARD`, and `DONE`. Compare against the enums shipped by the package rather than duplicating runtime strings.

### Supported locales

| Value              | Language        |
| ------------------ | --------------- |
| `VoveLocale.EN`    | English         |
| `VoveLocale.FR`    | French          |
| `VoveLocale.DE`    | German          |
| `VoveLocale.AR`    | Arabic          |
| `VoveLocale.AR_MA` | Moroccan Arabic |

## Configuration

| Field                 | Required | Default | Description                                                                     |
| --------------------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `environment`         | Yes      | —       | `Sandbox` with Sandbox credentials or `Production` with Production credentials. |
| `sessionToken`        | Yes      | —       | Fresh token created by your backend.                                            |
| `showUI`              | No       | `true`  | Show built-in welcome and summary screens.                                      |
| `exitAfterEachStep`   | No       | `false` | Return after each configured step.                                              |
| `enableVocalGuidance` | No       | `false` | Enable supported spoken guidance.                                               |
| `locale`              | No       | `EN`    | SDK UI locale.                                                                  |

## Step-by-step journey

```typescript
import {
  start,
  VoveEnvironment,
} from '@vove-id/react-native-sdk';

const result = await start({
  environment: VoveEnvironment.Sandbox,
  sessionToken: tokenFromYourBackend,
  exitAfterEachStep: true,
  showUI: false,
});

if (result.nextStep) {
  navigation.navigate('VerificationInterstep', { nextStep: result.nextStep });
}
```

Possible next steps are `LIVENESS`, `ID_DOCUMENT`, `DRIVING_LICENSE`, `ADDRESS_PROOF`, `CAR_REGISTRATION_CARD`, and `DONE`.

## Max-attempts listener

```typescript
import {
  addMaxAttemptsListener,
  removeMaxAttemptsListener,
} from '@vove-id/react-native-sdk';

useEffect(() => {
  addMaxAttemptsListener(showSupportOptions);

  return () => {
    removeMaxAttemptsListener();
  };
}, []);
```

Register once and clean up the listener when the owning component unmounts.

## Migration from 1.5.x

Since the 1.6.x line, `start()` returns `{ status, nextStep? }` instead of a status string.

```typescript
// Before
const status = await start(config);
if (status === 'success') {
  // ...
}

// Current
const result = await start(config);
if (result.status === VoveStatus.Success) {
  // ...
}
```

## Troubleshooting

| Symptom                         | Check                                                                                        |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| iOS native module is missing    | Run `pod install`, rebuild the native app, and do not rely on hot reload after installation. |
| Expo Go cannot load the SDK     | Use a development build with the native module and test the exact Expo version.              |
| Camera does not open            | Confirm platform declarations and runtime authorization.                                     |
| Status comparison never matches | Use `VoveStatus`; cancellation is `cancelled` at runtime.                                    |
| `nextStep` is undefined         | It is optional and normally appears only when exiting between steps.                         |

See [SDK compatibility](/docs/sdks/compatibility.md), [session creation](/docs/kyc-api/verification-session.md), and [production readiness](/docs/production-readiness.md).