# React Native

Before integrating Kvalifika, it is recommended to follow the steps described in [Integration Guide](/kvalifika-1/integration/integration-guide.md) and [Initial Setup](/kvalifika-1/integration/initial-setup.md).

{% hint style="warning" %}
Naming of the properties and functions might be slightly modified depending on the version.
{% endhint %}

## Installation

Add NPM dependency by running

```javascript
npm install @kvalifika/react-native-sdk
```

or

```javascript
yarn add @kvalifika/react-native-sdk
```

### For React Native <0.60

If your React Native version is larger than >= 0.60, you can ignore this step. Otherwise, please run the following command:

`react-native link @kvalifika/react-native-sdk`

### iOS Specific Steps

&#x20;Add sources to Podfile and use minimum iOS version `11.0`

```javascript
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/Kvalifika/kvalifika-cocoapods-specs.git'
source 'https://github.com/Kvalifika/zoom-cocoapods-specs.git'

platform :ios, '11.0'
```

&#x20;Then navigate to `ios` folder and run `pod install`

{% hint style="warning" %}
`pod install` might take a long time!
{% endhint %}

### App Permissions

Please add the following permissions to your app's *Info.plist*, so that the Kvalifika iOS SDK can access a user's camera to run a verification. You can do this in the property list view or by code. Right-click on *Info.plist* and select Open As -> Source Code. Add the lines below somewhere inside the file:

```markup
<!-- permission strings to be include in info.plist -->
<key>NSCameraUsageDescription</key>
<string>Please give us access to your camera, to complete the verification.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Please give us access to your photo library to verify you.</string>
```

### **Create Objective C Bridging Header**

After the pods are installed, open your project's `.xcworkspace` file in Xcode. Add a blank Swift file to your project (File -> New -> Swift File), with a bridging header (it will prompt you to auto-create one).

Righ&#x74;**-**&#x63;lick on the project's name & select a new file.

![Creating Objective C Bridging Header - new file](/files/-Me5Bc7jqZPXgPqyEdj4)

1. Choose and create an empty Swift file:

![Creating Objective C Bridging Header - Swift file](/files/-Me5CYT42L_FidL0K9gc)

2\. Give the name to your file:

![Creating Objective C Bridging Header - naming Swift file](/files/-Me5CnGB1Wgw5vbn9obz)

3\. Select `Create Bridging Header`:

![Creating Objective C Bridging Header - final step](/files/-Me5DD5Wvd4lugqZudsX)

### Android Specific Parts

After installing NPM package, please do the following steps to set up the Android environment:

1. Please add the following lines to `android/build.gradle` file:
   1. Set `minSdkVersion` to `21` or higher
   2. Add maven URL to repositories: `maven { url 'https://s3.eu-central-1.amazonaws.com/com.kvalifika.sdk' }`

**Code Example**

```javascript
// Top-level build.gradle file

buildscript {
  ext {
    minSdkVersion = 21
  }
}

allprojects {
  repositories {
    google()
    jcenter()
    maven { url 'https://s3.eu-central-1.amazonaws.com/com.kvalifika.sdk' }
  }
}
```

## Initialize the SDK

```javascript
import {
  KvalifikaSDK,
  KvalifikaSDKLocale,
  KvalifikaSDKError,
} from '@kvalifika/react-native-sdk';
```

&#x20;After that, you need to initialize SDK in`useEffect`with **your appId.**

{% hint style="info" %}
appId is Application ID, generated from Admin Panel. See [Initial Setup](/kvalifika-1/integration/initial-setup.md#retrieve-application-ids) for details.
{% endhint %}

```javascript
const App = () => {
  useEffect(() => {
    KvalifikaSDK.initialize({
      appId: 'YOUR APP ID',
      locale: KvalifikaSDKLocale.EN,
    });
  }, []);

  return (
    <View>
      <Text>Kvalifika SDK Sample</Text>
    </View>
  );
};
```

## **Start Verification**

&#x20;Call `KvalifikaSDK.startSession()` on button pres&#x73;**:**

```javascript
const App = () => {
  useEffect(() => {
    KvalifikaSDK.initialize({
      appId: 'YOUR APP ID',
      locale: KvalifikaSDKLocale.EN,
    });
  }, []);

  return (
    <View>
      <Button
        onPress={() => KvalifikaSDK.startSession()}
        title="Start Session"
      />
    </View>
  );
};
```

## Handling Verifications

It's useful to know that whether a user has completed the verification flow or canceled it. For this, you can implement the callback methods.

### Callback Methods

| Method       | Description                                                                                                                               |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| onInitialize | This callback method is triggered when SDK is initialized.                                                                                |
| onStart      | This callback method is triggered when the user starts verification.                                                                      |
| onFinish     | This callback method is triggered when the user completes verification. Get session data here.                                            |
| onError      | This callback method is triggered on error  (see [Error Codes](/kvalifika-1/mobile-sdk/react-native.md#error-codes) for more information) |

{% hint style="warning" %}
KvalifikaSDK uses NativeEventEmitter to communicate between Android and iOS native modules. **Make sure to remove callbacks on unmount.**
{% endhint %}

```javascript
const App = () => {
  useEffect(() => {
    KvalifikaSDK.onInitialize(() => {
      Alert.alert('Kvalifika', 'Kvalifika SDK Initialized');
    });

    KvalifikaSDK.onStart(sessionId => {
      console.log(`Started with id: ${sessionId}`);
    });

    KvalifikaSDK.onFinish(sessionId => {
      Alert.alert('Kvalifika', `Session finished with id: ${sessionId}`);
    });

    KvalifikaSDK.onError((error, message) => {
      console.log(error, message);

      if (error === KvalifikaSDKError.INVALID_APP_ID) {
      }

      if (error === KvalifikaSDKError.USER_CANCELLED) {
      }

      if (error === KvalifikaSDKError.TIMEOUT) {
      }

      if (error === KvalifikaSDKError.USER_CANCELLED) {
      }

      if (error === KvalifikaSDKError.SESSION_UNSUCCESSFUL) {
      }

      if (error === KvalifikaSDKError.ID_UNSUCCESSFUL) {
      }

      if (error === KvalifikaSDKError.CAMERA_PERMISSION_DENIED) {
      }

      if (error === KvalifikaSDKError.LANDSCAPE_MODE_NOT_ALLOWED) {
      }

      if (error === KvalifikaSDKError.REVERSE_PORTRAIT_NOT_ALLOWED) {
      }

      if (error === KvalifikaSDKError.FACE_IMAGES_UPLOAD_FAILED) {
      }

      if (error === KvalifikaSDKError.DOCUMENT_IMAGES_UPLOAD_FAILED) {
      }
      
      if (error === KvalifikaSDKError.NO_MORE_ATTEMPTS) {
      }

      if (error === KvalifikaSDKError.UNKNOWN_INTERNAL_ERROR) {
      }
    });

    return () => {
      // Remove callbacks to avoid duplicate listeners if useEffect runs multiple times or remounts
      KvalifikaSDK.removeCallbacks();
    };
  }, []);

  useEffect(() => {
    KvalifikaSDK.initialize({
      appId: 'YOUR APP ID',
      locale: KvalifikaSDKLocale.EN,
    });
  }, []);

  return (
    <View>
      <Button
        onPress={() => KvalifikaSDK.startSession()}
        title="Start Session"
      />
    </View>
  );
};
```

## Error Codes

| Error Code                       | Description                                                                              |
| -------------------------------- | ---------------------------------------------------------------------------------------- |
| INVALID\_APP\_ID                 | Kvalifika App Id is incorrect                                                            |
| USER\_CANCELLED                  | User canceled before completing verification.                                            |
| TIMEOUT                          | Canceled due to inactivity.                                                              |
| SESSION\_UNSUCCESSFUL            | The Session was not performed successfully.                                              |
| ID\_UNSUCCESSFUL                 | The ID Scan was not performed successfully and identity document data was not generated. |
| CAMERA\_PERMISSION\_DENIED       | Camera is required but access is prevented by user settings.                             |
| LANDSCAPE\_MODE\_NOT\_ALLOWED    | Verification was canceled because the device is in landscape mode.                       |
| REVERSE\_PORTRAIT\_NOT\_ALLOWED  | Verification was canceled because the device is in reverse portrait mode.                |
| FACE\_IMAGES\_UPLOAD\_FAILED     | Could not upload face images. Internal request failed.                                   |
| DOCUMENT\_IMAGES\_UPLOAD\_FAILED | Could not upload ID card or passport images. Internal request failed.                    |
| NO\_MORE\_ATTEMPTS               | User has reached maximum limit of attempts                                               |
| UNKNOWN\_INTERNAL\_ERROR         | Session failed because of an unhandled internal error. This error comes with a message.  |

## UI Customizations

### Appearance

It is possible to customize the logo and icons.

In React Native we need to add the images in `android` and `ios` subfolders in the project directory.

{% hint style="info" %}
Open `android` subfolder in Android Studio and drag the image to `res/drawable` folder.
{% endhint %}

{% hint style="info" %}
Open `ios` subfolder in XCode. Open `Assets.xcassets` folder and drag the image.
{% endhint %}

{% hint style="warning" %}
An image name in `android` and `ios` subfolders must match.
{% endhint %}

```typescript
KvalifikaSDK.initialize({
  appId: 'YOUR APP ID',
  locale: KvalifikaSDKLocale.EN,
  logo: 'logo',
  documentIcon: 'document_icon',
  cancelIcon: 'cancel_icon',
  activeFlashIcon: 'active_flash_icon',
  inactiveFlashIcon: 'inactive_flash_icon',
});
```

### Language

It is possible to set locale when initializing SDK. Supported locales are:

| Code | Language |
| ---- | -------- |
| EN   | English  |
| GE   | Georgian |
| RU   | Russian  |
| SP   | Spanish  |

```javascript
KvalifikaSDK.initialize({
  appId: 'YOUR APP ID',
  locale: KvalifikaSDKLocale.EN,
});
```

## Development Mode

Without specifying mode SDK uses <https://api.kvalifika.com>

With development mode ON SDK uses <https://apistaging.kvalifika.com>

```typescript
KvalifikaSDK.initialize({
  appId: 'YOUR APP ID',
  development: true,
});
```

## ProGuard (Android)

If ProGuard is used in Android release build, it is possible to add the following options to ProGuard file:

```javascript
-keep class com.facetec.sdk.** { *; }
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kvalifika.gitbook.io/kvalifika-1/mobile-sdk/react-native.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.