# React Native

### Introduction

The React Native VoveSDK facilitates easy integration of ID verification and KYC (Know Your Customer) compliance into mobile applications, supporting both iOS and Android platforms. This wrapper abstracts the complexity of interacting with the native VoveSDK, providing a simplified, promise-based JavaScript API for React Native developers.

### Requirements

* React Native 0.71+
* iOS 13.0+
* Android minSdk 24, compileSdk 34
* Kotlin 2.0.0+ (compatible with Expo SDK 54)

### Installation

To include the React Native VoveSDK in your project, install it via npm or Yarn:

```bash
npm install @vove-id/react-native-sdk
```

or

```bash
yarn add @vove-id/react-native-sdk
```

This package comes bundled with all necessary native dependencies, so there's no need for additional modifications to your `Podfile` or `build.gradle`.

### Permissions (iOS)

For VoveSDK to function properly, it is essential to request and obtain camera permission from the users. This permission is crucial for ID verification processes that require access to the device's camera. To request camera permission, add the following key to your Info.plist file:

```xml
<key>NSCameraUsageDescription</key>
<string>This application requires access to the camera for ID verification purposes.</string>
```

### Permissions (Android)

Add the necessary camera permission to your `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.CAMERA"/>
```

### Usage

The core functionality of the VoveSDK is to perform ID verification through a straightforward function call, which manages the verification process based on a session token.

#### Initialize Vove SDK

To initialize the Vove SDK, use your public API key. This setup should ideally be done in the main entry file (e.g., `App.js` or `index.js`) as early as possible.

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

initialize({
  environment: VoveEnvironment.Sandbox, // or VoveEnvironment.Production
  publicKey: 'YOUR_PUBLIC_KEY',
})
  .then(() => console.log('SDK Initialized'))
  .catch((e) => console.error('Initialization failed:', e));
```

#### Starting ID Verification

To start the ID verification process, use the `start` function. This function requires a configuration object that includes the session token and optional settings.

**Function Signature**

```typescript
start(config: VoveStartConfig): Promise<VoveVerificationResult>
```

**Configuration Options (`VoveStartConfig`)**

| Parameter             | Type              | Required | Default | Description                                               |
| --------------------- | ----------------- | -------- | ------- | --------------------------------------------------------- |
| `environment`         | `VoveEnvironment` | Yes      | -       | `VoveEnvironment.Production` or `VoveEnvironment.Sandbox` |
| `sessionToken`        | `string`          | Yes      | -       | Token generated by your backend to initiate the session   |
| `showUI`              | `boolean`         | No       | `true`  | Show/hide the SDK's built-in welcome and summary screens  |
| `exitAfterEachStep`   | `boolean`         | No       | `false` | Return control after each verification step               |
| `enableVocalGuidance` | `boolean`         | No       | `false` | Enable voice instructions during verification             |
| `locale`              | `VoveLocale`      | No       | `EN`    | Localize the verification UI                              |

**Return Type (`VoveVerificationResult`)**

```typescript
type VoveVerificationResult = {
  status: VoveStatus;
  nextStep?: VoveVerificationStep; // Only present when exitAfterEachStep is true
};
```

**Example Usage**

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

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

switch (result.status) {
  case VoveStatus.Success:
    console.log('Verification successful');
    break;
  case VoveStatus.Pending:
    console.log('Verification pending review');
    break;
  case VoveStatus.Canceled:
    console.log('User canceled verification');
    break;
  case VoveStatus.Failure:
    console.log('Verification failed');
    break;
  case VoveStatus.MaxAttempts:
    console.log('Maximum attempts reached');
    break;
}
```

#### Verification Status Values (`VoveStatus`)

| Status         | Description                           |
| -------------- | ------------------------------------- |
| `success`      | Verification completed successfully   |
| `pending`      | Verification requires manual review   |
| `cancelled`    | User canceled the verification        |
| `failure`      | Verification failed                   |
| `max-attempts` | Maximum verification attempts reached |

#### Step-by-Step Verification with `exitAfterEachStep`

Enable `exitAfterEachStep` to get control back after each verification step. This is useful when you want to interleave custom screens or logic between verification steps.

```typescript
const result = await start({
  environment: VoveEnvironment.Sandbox,
  sessionToken: 'your_session_token_here',
  exitAfterEachStep: true,
});

console.log('Current status:', result.status);
console.log('Next step:', result.nextStep); // e.g., 'LIVENESS', 'ID_DOCUMENT', 'DONE'

// Handle the next step in your app logic
if (result.nextStep === VoveVerificationStep.Done) {
  console.log('All steps completed!');
} else {
  // Continue with the next step when ready
}
```

**Verification Steps (`VoveVerificationStep`)**

| Step                    | Description                       |
| ----------------------- | --------------------------------- |
| `LIVENESS`              | Liveness/selfie verification      |
| `ID_DOCUMENT`           | ID document capture               |
| `DRIVING_LICENSE`       | Driving license capture           |
| `ADDRESS_PROOF`         | Address proof document capture    |
| `CAR_REGISTRATION_CARD` | Car registration document capture |
| `DONE`                  | All verification steps completed  |

#### Localization with VoveLocale

The SDK supports multiple languages for ID verification processes:

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

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

await start({
  sessionToken: 'your_session_token_here',
  locale: VoveLocale.FR, // French UI
});
```

#### Enabling Vocal Guidance

To enhance the user experience during ID verification, vocal guidance can be enabled. This feature provides audio instructions to help guide users through the verification process.

```typescript
await start({
  sessionToken: 'your_session_token_here',
  enableVocalGuidance: true,
});
```

#### Hiding the Welcome and Summary Pages

Control whether the SDK displays its built-in welcome and summary screens using the `showUI` parameter. Set to `false` to fully manage the user experience within your app.

```typescript
await start({
  sessionToken: 'your_session_token_here',
  showUI: false, // Hide built-in UI screens
});
```

#### Max Attempts Callback

Listen for the max attempts callback to handle scenarios where users reach the maximum number of verification attempts:

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

// Add listener
addMaxAttemptsListener(() => {
  console.log('Max attempts reached - show support options');
  // Navigate to support screen or show contact options
});

// Remove listener when done (e.g., in cleanup)
removeMaxAttemptsListener();
```

### Migration from v1.5.x to v1.6.x

#### Breaking Change: Return Type

The `start()` function now returns an object instead of a string:

**Before (v1.5.x):**

```typescript
const status = await start(config);
// status was a string: 'success', 'pending', etc.
```

**After (v1.6.x):**

```typescript
const result = await start(config);
// result is an object: { status: 'success', nextStep?: 'LIVENESS' }
console.log(result.status);   // Access the status
console.log(result.nextStep); // Access next step (when exitAfterEachStep is true)
```

### Troubleshooting

**Common Issues:**

1. **SDK not initializing**: Ensure you call `initialize()` before `start()` and that your public key is correct.
2. **Camera permission denied**: Make sure you've added the required permissions to `Info.plist` (iOS) and `AndroidManifest.xml` (Android).
3. **Kotlin version mismatch (Android)**: The SDK requires Kotlin 2.0.0+. If using Expo SDK 54 or React Native 0.81+, ensure your project is configured for Kotlin 2.0.
4. **Session token errors**: Verify the session token is correctly generated by your backend and hasn't expired.

### Support

For further assistance or inquiries about the React Native VoveSDK, please reach out to our support team at <support@voveid.com>.