> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native SDK for Cross-Platform Verification

> Run Dojah verification in React Native. One codebase for iOS and Android, same flows as web and native SDKs.

<Warning> All file links (e.g. selfie URLs, document URLs) returned in the response expire within **one hour**. We strongly recommend transferring these documents and images to your own infrastructure as soon as you receive them. If a link expires before you are able to download the file, call the [Fetch KYC widget Verification Data](/docs/technical-reference/get-verification-details) endpoint to generate a new link — which will also expire in one hour. </Warning>

### Installation \[CLI]

```sh theme={null}
npm install dojah-kyc-sdk-react_native
```

```sh yarn theme={null}

yarn add dojah-kyc-sdk-react_native
```

**Configuration and usage**

Reference : [https://www.npmjs.com/package/dojah-kyc-sdk-react\_native](https://www.npmjs.com/package/dojah-kyc-sdk-react_native)

Example Application: [https://github.com/dojah-inc/dojah-react-native-sdk](https://github.com/dojah-inc/dojah-react-native-sdk)

## Installation \[Expo]

```sh theme={null}
npm install dojah-kyc-sdk-react-expo
```

```sh theme={null}

yarn add dojah-kyc-sdk-react-expo
```

**Configuration and usage**

Reference : [https://www.npmjs.com/package/dojah-kyc-sdk-react-expo](https://www.npmjs.com/package/dojah-kyc-sdk-react-expo)

Example Application: [https://github.com/dojah-inc/dojah\_kyc\_sdk\_rn\_expo](https://github.com/dojah-inc/dojah_kyc_sdk_rn_expo)

### Setup

#### Install expo-build-properties if you don't have it

```sh theme={null}
npx expo install expo-build-properties
```

#### Add the following plugins and permissions in your app.json

```json theme={null}
{
  "expo": {
    ...
    "ios": {
      "infoPlist": {
        "NSLocationWhenInUseUsageDescription": "This app uses location services to provide a better experience.",
        "NSLocationAlwaysUsageDescription": "This app uses location services to provide a better experience.",
        "NSLocationUsageDescription": "This app uses location services to provide a better experience.",
        "NSPhotoLibraryUsageDescription": "This app uses the photo library to provide a better experience.",
        "NSCameraUsageDescription": "This app uses the camera to provide a better experience.",
        "NSMicrophoneUsageDescription": "This app uses the microphone to provide a better experience."
      }
    },
    "plugins": [
      ...
      "dojah-kyc-sdk-react-expo",
      [
        "expo-build-properties",
        {
          "ios": {
            "extraPods": [
              {
                "name": "Realm",
                "version": "~> 10.52.2",
                "modular_headers": true
              },
              {
                "name": "DojahWidget",
                "git": "https://github.com/dojah-inc/sdk-swift.git",
                "branch": "pod-package"
              }
            ]
          }
        }
      ]
    ]
  }
}
```

### Run prebuild:

```sh theme={null}
npx expo prebuild
```

## Android Setup

### Requirements

* Minimum Android SDK version - 21
* Supported targetSdkVersion - 35

In your android root/build.gradle file set maven path:

```
...
allprojects {
    repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}
```

Or Set maven path in your root/settings.gradle file:

```
...
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}
```

### Permissions

For Android you don't need to declare permissions, its already included in the Package.

### ProGuard / R8 Configuration (Android)

If you have ProGuard or R8 minification and resource shrinking enabled for your Android release builds, you must add keep rules so that the Dojah SDK classes and its dependencies are not stripped or obfuscated. Without these rules, the SDK may crash at runtime with `ClassNotFoundException`, `NoSuchMethodError`, or silent WebView/JavaScript bridge failures.

<Tabs>
  <Tab title="CLI (React Native)">
    <Steps>
      <Step title="Enable minification in build.gradle">
        In your `android/app/build.gradle`, enable ProGuard (R8) for release builds:

        ```groovy theme={null}
        android {
            ...
            buildTypes {
                release {
                    minifyEnabled true
                    shrinkResources true
                    proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
                }
            }
        }
        ```
      </Step>

      <Step title="Add Dojah ProGuard rules">
        Create or open the file `android/app/proguard-rules.pro` and add the following rules:

        ```
        # ── Dojah SDK ──
        -keep class com.dojah.** { *; }
        -keep class com.dojah_inc.** { *; }
        -keepclassmembers class com.dojah.** { *; }
        -dontwarn com.dojah.**

        # ── Android WebView JavaScript bridge ──
        -keepclassmembers class * {
            @android.webkit.JavascriptInterface <methods>;
        }
        -keepattributes JavascriptInterface

        # ── Retrofit (used internally by the SDK) ──
        -keepattributes Signature,InnerClasses,EnclosingMethod
        -keepattributes RuntimeVisibleAnnotations,RuntimeVisibleParameterAnnotations
        -keepattributes AnnotationDefault
        -keepclassmembers,allowshrinking,allowobfuscation interface * {
            @retrofit2.http.* <methods>;
        }
        -if interface * { @retrofit2.http.* <methods>; }
        -keep,allowobfuscation interface <1>
        -keep,allowobfuscation,allowshrinking interface retrofit2.Call
        -keep,allowobfuscation,allowshrinking class retrofit2.Response
        -keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
        -dontwarn retrofit2.KotlinExtensions
        -dontwarn retrofit2.KotlinExtensions$*

        # ── OkHttp / Okio ──
        -dontwarn okhttp3.**
        -dontwarn okio.**

        # ── Gson ──
        -keep class sun.misc.Unsafe { *; }
        -keep class com.google.gson.** { *; }

        # ── Glide (image loading) ──
        -keep public class * implements com.bumptech.glide.module.GlideModule
        -keep class * extends com.bumptech.glide.module.AppGlideModule {
            <init>(...);
        }
        -keep public enum com.bumptech.glide.load.ImageHeaderParser$** {
            **[] $VALUES;
            public *;
        }
        -keep class com.bumptech.glide.load.data.ParcelFileDescriptorRewinder$InternalRewinder {
            *** rewind();
        }

        # ── Misc ──
        -dontwarn javax.annotation.**
        -dontwarn kotlin.Unit
        -dontwarn org.codehaus.mojo.animal_sniffer.*
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Expo">
    If you are using Expo, you can apply ProGuard rules directly in your `app.config.ts` (or `app.json`) using the `expo-build-properties` plugin without creating a separate `proguard-rules.pro` file:

    ```typescript theme={null}
    android: {
      minSdkVersion: 26,
      compileSdkVersion: 35,
      targetSdkVersion: 35,
      enableProguardInReleaseBuilds: true,
      enableShrinkResourcesInReleaseBuilds: true,
      extraProguardRules: [
        '-keep class com.dojah.** { *; }',
        '-keep class com.dojah_inc.** { *; }',
        '-keepclassmembers class com.dojah.** { *; }',
        '-keepclassmembers class * { @android.webkit.JavascriptInterface <methods>; }',
        '-keepattributes JavascriptInterface',
        '-keepattributes Signature,InnerClasses,EnclosingMethod',
        '-keepattributes RuntimeVisibleAnnotations,RuntimeVisibleParameterAnnotations',
        '-keepattributes AnnotationDefault',
        '-keepclassmembers,allowshrinking,allowobfuscation interface * { @retrofit2.http.* <methods>; }',
        '-dontwarn javax.annotation.**',
        '-dontwarn kotlin.Unit',
        '-dontwarn retrofit2.KotlinExtensions',
        '-dontwarn retrofit2.KotlinExtensions$*',
        '-if interface * { @retrofit2.http.* <methods>; }',
        '-keep,allowobfuscation interface <1>',
        '-keep,allowobfuscation,allowshrinking interface retrofit2.Call',
        '-keep,allowobfuscation,allowshrinking class retrofit2.Response',
        '-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation',
        '-dontwarn org.codehaus.mojo.animal_sniffer.*',
        '-keep class sun.misc.Unsafe { *; }',
        '-keep class com.google.gson.** { *; }',
        '-keep public class * implements com.bumptech.glide.module.GlideModule',
        '-keep class * extends com.bumptech.glide.module.AppGlideModule { <init>(...); }',
        '-keep public enum com.bumptech.glide.load.ImageHeaderParser$** { **[] $VALUES; public *; }',
        '-keep class com.bumptech.glide.load.data.ParcelFileDescriptorRewinder$InternalRewinder { *** rewind(); }',
        '-dontwarn com.dojah.**',
        '-dontwarn okhttp3.**',
        '-dontwarn okio.**',
      ].join('\n'),
    },
    ```

    Then run `npx expo prebuild` to regenerate your native project with the updated rules.
  </Tab>
</Tabs>

<Warning>
  Failing to add these rules when ProGuard/R8 is enabled will cause the Dojah SDK to malfunction in release builds. Common symptoms include blank screens, crashes on SDK launch, and network call failures. If you encounter issues, run a release build with `--no-shrink` temporarily to confirm ProGuard is the cause.
</Warning>

### iOS Setup

#### Requirements

* Minimum iOS version - 14

#### Add the following POD dependencies in your Podfile app under your App target

```
  pod 'Realm', '~> 10.52.2', :modular_headers => true
  pod 'DojahWidget', :git => 'https://github.com/dojah-inc/sdk-swift.git', :branch => 'pod-package'
```

example

```
target 'Example' do
  ...
  pod 'Realm', '~> 10.52.2', :modular_headers => true
  pod 'DojahWidget', :git => 'https://github.com/dojah-inc/sdk-swift.git', :branch => 'pod-package'
  ...
end
```

and run pod install in your iOS folder:

```sh theme={null}
cd iOS
pod install
```

### Make some few changes in your AppDelegate.mm file

* Add the following imports:

```objective-c theme={null}
#import <React/RCTBridge.h>
#import <React/RCTRootView.h>
```

* Then replace application function in your AppDelegate with the following:

`REMEMBER TO CHANGE THE Your App Name,to the actual name of your App`

```objective-c theme={null}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  // Initialize the React Native bridge
  RCTBridge *bridge = [[RCTBridge alloc] initWithDelegate:self launchOptions:launchOptions];

  RCTRootView *rootView = [[RCTRootView alloc] initWithBridge:bridge
                                                   moduleName:@"Your App Name"
                                            initialProperties:nil];

  UIViewController *rootViewController = [UIViewController new];
  rootViewController.view = rootView;

  // Wrap rootViewController in a UINavigationController
  UINavigationController *navigationController = [[UINavigationController alloc] initWithRootViewController:rootViewController];

  self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
  self.window.rootViewController = navigationController;
  [self.window makeKeyAndVisible];

  return YES;
}

```

### Permissions

For iOS, Add the following keys to your Info.plist file:

NSCameraUsageDescription - describe why your app needs access to the camera. This is called Privacy - Camera Usage Description in the visual editor.

NSMicrophoneUsageDescription - describe why your app needs access to the microphone, if you intend to record videos. This is called Privacy - Microphone Usage Description in the visual editor.

NSLocationWhenInUseUsageDescription - describe why your app needs access to the location, if you intend to verify address/location. This is called Privacy - Location Usage Description in the visual editor.

### Usage

To start KYC, import Dojah in your React Native code, and launch Dojah Screen

```js theme={null}
import {launchDojahKyc } from 'dojah-kyc-sdk-react_native';

launchDojahKyc(
  "{Required: Your_WidgetID}",
  "{Optional: Reference_ID}",
  "{Optional: Email_Address}"
)


//Example (If you're not passing Reference_ID and Email_Address values)

launchDojahKyc("1234678901234", "DJ-123456", "abc@gmail.com")


//Example (If you're not passing Reference_ID and Email_Address values)

launchDojahKyc("1234678901234", null, null)



```

### SDK Parameters

* `WidgetID` - a `REQUIRED` parameter. You get this ID when you sign up on the Dojah platform, follow the next step to generate your WidgetId.
* `Reference ID` - an `OPTIONAL` parameter that allows you to initialize the SDK for an ongoing verification.
* `Email Address` - an `OPTIONAL` parameter that allows you to initialize the SDK for an ongoing verification.

### How to Get a Widget ID

To use the SDK, you need a WidgetID, which is a required parameter for initializing the SDK. You can obtain this by creating a flow on the Dojah platform. Follow these steps to configure and get your Widget ID:

```txt theme={null}
1. Log in to your Dojah Dashboard: If you don’t have an account, sign up on the Dojah platform.

2. Navigate to the EasyOnboard Feature: Once logged in, find the EasyOnboard section on your dashboard.

3. Create a Flow:

    - Click on the 'Create a Flow' button.
    - Name Your Flow: Choose a meaningful name for your flow, which will help you identify it later.

4. Add an Application:

    - Either create a new application or add an existing one.
    - Customise your widget with your brand logo and color by selecting an application.

5. Configure the Flow:

    - Select a Country: Choose the country or countries relevant to your verification process.
    - Select a Preview Process: Decide between automatic or manual verification.
    - Notification Type: Choose how you’d like to receive notifications for updates (email, SMS, etc.).
    - Add Verification Pages: Customize the verification steps in your flow (e.g., ID verification, address verification, etc.).

6. Publish Your Widget: After configuring your flow, publish the widget. Once published, your flow is live.

7. Copy Your Widget ID: After publishing, the platform will generate a Widget ID. Copy this Widget ID as you will need it to initialize the SDK as stated above.
```

### Contributing

* \[KYC WIDGET Repository] ([https://github.com/dojah-inc/dojah-react-native-sdk](https://github.com/dojah-inc/dojah-react-native-sdk))
* Fork it!
* Create your feature branch: `git checkout -b feature/feature-name`
* Commit your changes: `git commit -am 'Some commit message'`
* Push to the branch: `git push origin feature/feature-name`
* Submit a pull request 😉😉

### WebView (Use this if you need custom UI not provided by launchDojahKyc)

-Usage

```jsx Webview theme={null}
<WebView
    originWhitelist={['*']}
    source={{uri: 'https://identity.dojah.io?widget_id=12345678&user_data[first_name]=John&user_data[middle_name]=Doe&user_data[last_name]=Musa&user_data[email]&user_data[dob]=1900-04-30&metadata[user_id]='}}
    allowsInlineMediaPlayback={true}
    mediaPlaybackRequiresUserAction={false}
    startInLoadingState={true}
    javaScriptEnabled
    onError={e => console.log('error: ', e)}
  />

```

-NB: Kindly input your widget\_id inside uri above, Get it from your Easy Onboard application dashboard [here](https://app.dojah.io/easy-onboard)

<Warning>
  **Important Security Update: Proper Handling of SDK Verification Callbacks**

  The final verification decision should **never** rely on SDK callbacks (`onSuccess`, `onError`, `onClose`) alone. Always retrieve the actual verification status from your backend using the reference ID before granting access or approving onboarding.
</Warning>

<AccordionGroup>
  <Accordion title="onSuccess — All verification steps completed">
    The `onSuccess` callback is triggered when the user has **completed all the verification steps** configured in the widget flow. This confirms that every step — such as document capture, liveness check, government data entry, etc. — has been submitted by the user.

    **Important:** `onSuccess` confirms flow completion, not that the user passed all checks. A user may complete every step but still fail backend validation (e.g., document mismatch, failed liveness). Always verify the final result from your backend using the **reference ID**.
  </Accordion>

  <Accordion title="onError — Error before all steps are completed">
    The `onError` callback is triggered when an error occurs **before all verification steps are completed**. This prevents the user from finishing the flow. Common causes include:

    * Network connectivity issues
    * SDK initialization or configuration errors
    * Provider-side failures during a verification step
    * Unexpected interruptions during the flow

    When `onError` fires, the verification is incomplete. Your application should handle this gracefully — for example, by prompting the user to retry.
  </Accordion>

  <Accordion title="onClose — Widget terminated via close button">
    The `onClose` callback is triggered when the user **terminates the widget using the close button**. This indicates the user chose to exit the verification flow before completing all steps.

    The verification is considered **abandoned** when this occurs. If a redirect URL is configured, the user will be redirected there after the widget closes. The final verification status will be delivered through the **webhook notification**.
  </Accordion>
</AccordionGroup>

<Note>
  **Recommended Implementation**

  After the widget interaction, create a backend flow or confirmation page that retrieves the actual verification result using the **reference ID** generated during the verification process. You can retrieve the final verification details through:

  * **Webhook notifications** — [Subscribe to services](/docs/technical-reference/subscribe-to-service)
  * **Verification Details API** — [Get verification details](/docs/technical-reference/get-verification-details)
</Note>

**Possible Verification Statuses**

The verification result returned by the webhook or API may contain any of the following statuses:

| Status        | Description                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| **Ongoing**   | The verification process is currently in progress.                               |
| **Completed** | The verification has been successfully completed and passed all checks.          |
| **Pending**   | The verification is awaiting further action or review.                           |
| **Failed**    | The verification was completed but did not pass one or more verification checks. |
| **Abandoned** | The verification was started but not completed by the user.                      |