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

# IDnow eID SDK - ReactNative Module

## Getting started

### Add the package to your dependencies

```sh
npm install @idnow/react-eid
```

---

## Usage

```ts
import * as idnowEID from '@idnow/react-eid';
// or
import { startEID } from '@idnow/react-eid';
```

### Start an eID identification session

```ts
import { startEID } from '@idnow/react-eid';

const startEIDIdentification = async (token: string) => {
  try {
    const result = await startEID(token);

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

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

      case 'FAILED':
        console.log('eID identification failed:', result.errorMessage);
        break;

      case 'CONTINUE_VIDEO_IDENT':
        console.log('User chose to continue with Video Ident instead.');
        // Handle fallback to Video Ident -- see "Fallback to Video Ident" section below
        break;
    }

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

### Fallback to Video Ident

When `startEID` resolves with a `CONTINUE_VIDEO_IDENT` status, the user has chosen to fall back to the Video Ident flow. It is up to the integrator to handle this by calling the VideoIdent SDK:

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

const startEIDWithFallback = async (token: string) => {
  try {
    const result = await startEID(token);

    if (result.status === 'CONTINUE_VIDEO_IDENT') {
      // Fall back to Video Ident
      const viResult = await startIdent(token);
      console.log('Video Ident result:', viResult.status);
    } else {
      console.log('eID result:', result.status);
    }
  } catch (error) {
    console.error('Error code:', error.code);
    console.error('Error message:', error.message);
  }
};
```

> **Note:** The `@idnow/react-videoident` package must be installed separately if you want to support the Video Ident fallback.

---

## API Reference

### `startEID(token: string): Promise<EIDResult>`

Starts the native IDnow eID SDK for an identification session using an NFC-enabled ID card.

**Parameters:**

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

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

---

## Result Types

### `EIDResult`

```ts
interface EIDResult {
  status: EIDStatus;
  transactionToken?: string;
  errorMessage?: string;
}
```

### `EIDStatus`

| Status | Description |
|---|---|
| `SUCCESS` | eID identification completed successfully |
| `FAILED` | eID identification failed |
| `CANCELLED` | User cancelled the eID identification |
| `CONTINUE_VIDEO_IDENT` | User chose to continue with Video Ident instead |

---

## Error Handling

`startEID` 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 startEID(token);
} catch (error) {
  console.error(error.code);
  console.error(error.message);
}
```

### Error Codes

| Error Code | Description |
|---|---|
| `EID_UNSUPPORTED_NFC` | NFC is not available on this device |
| `NFC_NOT_SUPPORTED` | Device does not support NFC |
| `EID_USER_CANCELLED` | User cancelled the eID process |
| `EID_INVALID_TOKEN` | The supplied token is invalid |
| `EID_PRECONDITION_FAILED` | Preconditions not met (e.g. expired or already used token) |
| `EID_TOKEN_UNSUPPORT_ELECTRONIC_CARD` | The document used is not supported for eID |
| `EID_UNKNOWN` | An undefined eID error occurred |
| `SDK_INIT_ERROR` | The eID SDK could not be initialized |

---

## Configure for iOS

### Requirements

- iOS 14.0 or higher
- NFC-capable device (iPhone 7 or higher)

### Private Framework

This plugin requires the `AuthadaAuthenticationLibrary.xcframework`, which is provided privately by your IDnow customer success manager.

Place it in a `vendor/` directory at the root of your project:

```
your-app/
├── vendor/
│   └── AuthadaAuthenticationLibrary.xcframework
├── ios/
├── package.json
└── ...
```

> **Note:** This framework must not be distributed publicly.

### NFC Entitlements

In your Xcode project:

1. **Add the capability:** Select your app target → Signing & Capabilities → + Capability → **Near Field Communication Tag Reading**

2. **Update Info.plist** — add the following keys:

```xml
<key>NFCReaderUsageDescription</key>
<string>NFC is required to read your ID card for identification.</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>E80704007F00070302</string>
    <string>A0000002471001</string>
</array>
```

---

## Platform Support

| Platform | Supported                                                                                                                                                                                   |
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| iOS | ✅                                                                                                                                                                                           |
| Android | ❌ (use @idnow/react-videoident plugin for eID, then add this dependency to the android app/build.gradle: <br/> ```implementation ("de.idnow.android.eid:idnow-android-eid-sdk:x.x.x") ``` ) |

> **Note:** This eID plugin is currently only needed for iOS. Use a conditional import to avoid loading this module at runtime:

```js
let idnowEID = null;
if (Platform.OS === 'ios') {
  idnowEID = require('@idnow/react-eid');
}
```

---

## Additional Resources

- [Expo Documentation](https://docs.expo.dev/)
- [React Native Documentation](https://reactnative.dev/)