npm package: @idnow/react-videoident
Description: VideoIdent SDK - ReactNative module
Author: IDnow
Latest version: 0.0.4

# VideoIdent SDK - ReactNative Module

## Getting started

### Add the package to your dependencies

```sh
# with npm
npm install @idnow/react-videoident

# with yarn
yarn add @idnow/react-videoident
```

---

## Usage

```ts
import * as idnow from '@idnow/react-videoident';
// or
import { startIdent } from '@idnow/react-videoident';
```

### Start an identification session

```ts
import { startIdent } from '@idnow/react-videoident';

const startIdentification = async (token: string) => {
  try {
    const result = await startIdent(token);

    switch (result.status) {
      case 'SUCCESS':
        console.log('Identification completed. Token:', result.transactionToken);
        break;

      case 'CANCELLED':
        console.log('Identification cancelled:', result.errorMessage);
        break;

      case 'USER_IN_QUEUE':
        console.log('User enrolled in waiting list. Will be notified via SMS.');
        break;

      case 'WRONG_IDENT':
        // Android only
        console.log('Wrong identification token:', result.errorMessage);
        break;
    }

  } catch (error) {
    console.error('Error code:', error.code);
    console.error('Error message:', error.message);
  }
};
```

---

## API Reference

### `startIdent(token: string): Promise<IdNowResult>`

Starts the native IDnow VideoIdent SDK for an identification session.

**Parameters:**

- `token` — A string representing the Identification Token.

**Returns:** A `Promise` that resolves with an `IdNowResult` object or rejects with an error.

---

## Result Types

### `IdNowResult`

```ts
interface IdNowResult {
  status: IdNowStatus;
  transactionToken?: string;
  errorMessage?: string;
}
```

### `IdNowStatus`

| Status | Description | Platform |
|---|---|---|
| `SUCCESS` | Identification completed successfully | iOS & Android |
| `CANCELLED` | User cancelled the identification | iOS & Android |
| `USER_IN_QUEUE` | User enrolled in waiting list, will be notified via SMS | iOS & Android |
| `WRONG_IDENT` | User used a wrong identification token | Android only |

---

## Error Handling

`startIdent` returns a `Promise`. When the identification process encounters a fatal error, the promise is **rejected** with an error object containing a `code` and a `message`.

```ts
try {
  const result = await startIdent(token);
} catch (error) {
  console.error(error.code);  
  console.error(error.message);
}
```

### Error Codes

| Error Code | Description | Platform |
|---|---|---|
| `IDnowErrorMissingTransactionToken` | The identification token is missing or invalid | iOS & Android |
| `IDnowErrorOfficeClosed` | Identification not available outside business hours | iOS & Android |
| `IDnowErrorUnsupportedDevice` | Device does not meet minimal requirements | iOS & Android |
| `IDnowErrorCameraAccessNotGranted` | Camera permission was not granted | iOS & Android |
| `IDnowErrorMicrophoneAccessNotGranted` | Microphone permission was not granted | iOS & Android |
| `IDnowErrorNoInternetConnection` | No internet connection available | iOS & Android |
| `IDnowErrorServer` | A server error occurred | iOS & Android |
| `IDnowErrorWebRTC` | Could not establish a video connection | iOS & Android |
| `IDnowErrorIdentificationFailed` | The identification process failed | iOS & Android |
| `IDnowErrorHighCallVolumeTryLater` | High call volume, user agreed to try later | iOS & Android |
| `IDnowErrorTokenNotSupported` | Token is meant for a different product | iOS & Android |
| `IDnowErrorTokenNotSupported_eIDStandalone` | eID standalone token cannot be used for VideoIdent | iOS & Android |
| `IDnowErrorUnsupportedProduct` | Product is no longer supported | iOS & Android |
| `IDnowErrorUnsupportedBluetoothHeadset` | Bluetooth headset used despite being disabled | iOS & Android |
| `IDnowInstantSignDocumentExpired` | The trusted document has expired | iOS & Android |
| `IDnowErrorJailbreakPhoneNotSupported` | Identification not supported on jailbroken devices | iOS only |
| `IDnowErrorRootedPhoneNotSupported` | Identification not supported on rooted devices | Android only |
| `SDK_INIT_ERROR` | The IDnow SDK could not be initialized | iOS & Android |
| `IDENT_FAILED` | Identification failed with no specific error code | iOS & Android |

---

## Configure for iOS

### Requirements

- iOS 14.0 or higher

### Permissions

Add the following keys to your `Info.plist`:

```xml
<key>NSCameraUsageDescription</key>
<string>This app requires camera access for identity verification.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app requires microphone access for identity verification.</string>
```

---

## Configure for Android

### Requirements

- Android SDK 26 or higher

### Dependencies

The IDnow VideoIdent SDK might requires those  **BouncyCastle** suite for cryptography and TLS. Add the following to your `build.gradle`:

```groovy
dependencies {
    implementation ("org.bouncycastle:bcprov-jdk15to18:1.72")
    implementation ("org.bouncycastle:bctls-jdk15to18:1.72")
    implementation ("org.bouncycastle:bcutil-jdk15to18:1.72")
}
```

> ⚠️ All 3 BouncyCastle artifacts must use the **same version** to avoid runtime conflicts.

### Permissions

The following needed permissions are automatically included by the SDK. No manual addition is required:

---

## Platform Behaviour Differences

| Behaviour | iOS | Android |
|---|---|---|
| `WRONG_IDENT` status | Not available | ✅ Available |
| Jailbreak/Root detection error | `IDnowErrorJailbreakPhoneNotSupported` | `IDnowErrorRootedPhoneNotSupported` |
| Server HTTP status code | Not exposed | Appended to error message on `IDnowErrorServer` |