nashidverifysdk

v2.6.5

Published

3 months ago

The nashidverifysdk package provides a seamless interface to integrate the VerifySDK into your React Native application. It enables cross-platform access to the core features of the SDK for document verification and authentication, simplifying the process

Downloads

0High
0Medium
0Low

razinasir

react-native ios android

React Native Implementation for Nashid Verification SDK (iOS & Android)

Introduction

This document serves as a comprehensive guide for React Native developers to seamlessly integrate the VerifySDK into their applications. By following the step-by-step instructions provided, developers can simplify the process of scanning Oman ID cards and passports, and efficiently retrieve document scan results.

Nashid Verify SDK is designed to streamline identity verification processes, ensuring a smooth integration experience across platforms.

Prerequisites

Before you begin integrating the Nashid Verify SDK, ensure the following:

React Native environment.
Node.js
Npm or yarn.
Android Studio.
Latest Android Studio with SDK tools.
Xcode (16.1 or higher) for iOS development.
Gradle 8.0 or higher

Installation

Install the package by running the following command:
```
npm i nashidverifysdk
```

For iOS, do the following:

a. In your Podfile, add the following line to include Nashid Verify SDK:

target "YourApp" do
  config = use_native_modules!
  use_frameworks!
  use_react_native!(
    :path => config[:reactNativePath],
    :hermes_enabled => false,
    :app_path => "#{Pod::Config.instance.installation_root}/.."
  )

  post_install do |installer|
    react_native_post_install(
      installer,
      config[:reactNativePath],
      :mac_catalyst_enabled => false
    )
    installer.generated_projects.each do |project|
      project.targets.each do |target|
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0'
        end
      end
    end
    installer.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['DEBUG_INFORMATION_FORMAT'] = 'dwarf-with-dsym'
        config.build_settings['OTHER_SWIFT_FLAGS'] = '-no-verify-emitted-module-interface'
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        config.build_settings['ONLY_ACTIVE_ARCH'] = 'NO'
      end
    end
  end
end

b. Add the required permissions in your Info.plist file:

<key>NSCameraUsageDescription</key>
<string>We need access to the camera to scan documents.</string>
<key>NFCReaderUsageDescription</key>
<string>NFC permission is required to complete the full KYC process.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location permission is required to complete the full KYC process.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Location permission is required to complete the full KYC process.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Location permission is required to complete the full KYC process.</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A000000018524F500101</string>
  <string>A0000002471001</string>
  <string>A0000002472001</string>
  <string>00000000000000</string>
  <string>A00000024300130000000101</string>
  <string>A0000002430013000000010109</string>
  <string>A000000243001300000001FF</string>
</array>

c. Add the following script in Build Phases > Run Script:

#!/bin/bash

# Path to VerifySDK.framework inside the final .app bundle

APP_FRAMEWORKS_PATH="${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Frameworks/VerifySDK.framework"
echo "Checking for nested frameworks in: $APP_FRAMEWORKS_PATH"
if [ -d "${APP_FRAMEWORKS_PATH}/Frameworks" ]; then
  echo "Removing nested Frameworks directory from VerifySDK.framework..."
  rm -rf "${APP_FRAMEWORKS_PATH}/Frameworks"
  echo "Nested frameworks removed successfully."
else
  echo "No nested Frameworks directory found in VerifySDK.framework."
fi

d. Enable Near Field Communication (NFC) Reading capability in your projects, as follows:

Open your project in Xcode.
Navigate to your Target settings.
Go to the Signing & Capabilities tab.
Click the + Capability button.
Select Near Field Communication Tag Reading from the list.

e. Set Privacy Usage Description for NFC, as follows:

In Xcode, go to the Build Settings tab.
Search for Privacy - NFC Scan Usage Description.
Double-click the field and add desired description, for example: "Needed permission to read Passport's NFC"

f. Run:

cd ios && pod install

For Android, do the following:

a. Update AndroidManifest.xml:

xmlns:tools="http://schemas.android.com/tools"
tools:replace="android:name"
android:enableOnBackInvokedCallback="true"

b. Add the following lines to app-level build.gradle file:

android {
  compileSdk 34
  defaultConfig {
    minSdk 21
    targetSdk 34
  }
}

Usage

1. Import Nashid Verify SDK:

import {
  initialize,
  verify,
  getVerificationResult,
  DocumentType,
} from 'nashidverifysdk';

2. Initialize the SDK:

To start using the SDK, you need to create an SDK Application and configure the desired verification flow via your admin dashboard.

The initialize() function expects the following arguments:

SDK Application Key (Mandatory): The key generated using your Nashid Verify admin dashboard.
SDK Application Key Secret (Mandatory): The key secret generated using your Nashid Verify admin dashboard.
Language Code (Optional): en for English (default), ar for Arabic, etc.
Extra Data (Optional): An object of key-value pairs that you can use to annotate the verification data generated with additional data that your consumer application may need.

The initialize() function returns a value, indicating whether initialization was successful (true) or unsuccessful (false), along with an error message in case of unsuccessful initialization.

const message = await initialize(
  'Your SDK key',
  'Your SDK secret',
  'en', // Language (default: "en")
  {
    // optional extra data
    'example-key': 'example-value',
  }
);

3. Listen for SDK Exit Events

The Nashid Verify SDK provides a stream of exit events that notify you when the user cancels or completes a verification step (e.g., OcrCancelled, NfcCancelled, LivenessCancelled, or Completed). This is useful for handling user exits or cancellations in your React Native app UI.

How to use:

import { useEffect } from 'react';
import { Alert, NativeEventEmitter } from 'react-native';
import { NashIdVerifySdk } from 'nashidverifysdk';

useEffect(() => {
  // Initialize the SDK event emitter
  const sdkEmitter = new NativeEventEmitter(NashIdVerifySdk);

  // Start listening for 'onSDKExit' events
  const subscription = sdkEmitter.addListener('onSDKExit', (event) => {
    // event.exitStep will be one of: 'OcrCancelled', 'NfcCancelled', 'LivenessCancelled', 'Completed', or other custom values
    const exitStep = event.exitStep;

    if (exitStep === 'OcrCancelled') {
      // Handle document scanning cancellation
    } else if (exitStep === 'NfcCancelled') {
      // Handle NFC scanning cancellation
    } else if (exitStep === 'LivenessCancelled') {
      // Handle liveness check cancellation
    } else if (exitStep === 'MalaConsentDeclined') {
      // Handle Mala consent declined
    } else if (exitStep === 'Completed') {
      // Handle successful completion
    } else {
      // Handle unknown or unexpected exit step
    }

    // Optionally show an alert with the exit status
    Alert.alert('SDK Exit', `Verification exited with step: ${exitStep}`);
  });

  // To stop listening:
  return () => {
    subscription.remove();
  };
}, []);

4. Verify A Document Using Nashid Verify SDK:

Once Nashid Verify SDK is initialized successfully, you can start verifications journeys for your users using the verify() function.

This function accepts either a DocumentType enum (recommended) or a numeric value for the type of document to be verified.

| ID Type | Enum Name | Numeric Value | | ---------------------- | ------------------------------------- | :-----------: | | OMANI_ID | DocumentType.OMAN_ID | 1 | | INTERNATIONAL_PASSPORT | DocumentType.INTERNATIONAL_PASSPORT | 2 | | EMIRATI_ID | DocumentType.EMIRATES_ID | 3 | | SAUDI_ID | DocumentType.SAUDI_ID | 4 | | BAHRAINI_ID | DocumentType.BAHRAINI_ID | 5 | | QATARI_ID | DocumentType.QATARI_ID | 6 | | KUWAIT_ID | DocumentType.KUWAITI_ID | 7 |

And as a result of the verification flow, it returns three values:

Result: A boolean flag that is true when the verification flow is successful, and false otherwise.
Error Message: A string containing the error details in case of unsuccessful verification.
Verification ID: An ID of the created verification. This ID can be used later on to get the results collected with any additional checks/information annotated by backend services.

Examples Using Enum:

Example1: Verify With Omani ID

const result = await verify(DocumentType.OMAN_ID);

Example2: Verify With International Passport

const result = await verify(DocumentType.INTERNATIONAL_PASSPORT);

Example3: Verify With Emirati ID

const result = await verify(DocumentType.EMIRATES_ID);

Example4: Verify With Saudi ID

const result = await verify(DocumentType.SAUDI_ID);

Example5: Verify With Bahraini ID

const result = await verify(DocumentType.BAHRAINI_ID);

Example6: Verify With Qatari ID

const result = await verify(DocumentType.QATARI_ID);

Example7: Verify With Kuwait ID

const result = await verify(DocumentType.KUWAITI_ID);

5. Using Nashid Verify SDK To Get A Verification Result

Once you have a valid verification ID as an outcome of a successful verification journey, you can use the getVerificationResult() function to get the results collected with any additional checks/information annotated by backend services using the verification ID.

Example: Retrieve the data of verification ID abcd1234

const result = await getVerificationResult('abcd1234');

The verificationID (abcd1234) is just an example value that represents what we get as a result of the verify functionality.
Example Response For ID cards:

{
  "result": true,
  "errorMessage": "",
  "scanData": {
    "message": "Verification retrieved successfully.",
    "data": {
      "id": "dummy123456",
      "annotations": {},
      "data": {
        "NFC": {
          "issue_date": "2023-01-15",
          "full_name_arabic": "محمد أحمد علي",
          "country_of_birth_english": "Sample Country",
          "full_name_english": "MOHAMMED AHMED ALI",
          "date_of_birth": "1990-05-20",
          "gender_english": "Male",
          "place_of_issue_english": "Sample City",
          "country_of_birth_arabic": "دولة عينة",
          "place_of_issue_arabic": "مدينة عينة",
          "expiry_date": "2028-01-15",
          "nationality_english": "SAMPLE",
          "identity_number": "12345678",
          "nationality_arabic": "عينة",
          "gender_arabic": "ذكر",
          "company_name_english": "",
          "permit_type": "",
          "visa_number": "",
          "company_name_arabic": "",
          "company_address_arabic": "",
          "permit_number": "",
          "use_by_date": ""
        },
        "liveness": {
          "active_liveness_confirmed": true,
          "score": 0.95,
          "passive_liveness_confirmed": true
        },
        "scan": {
          "date_of_birth": "1990-05-20",
          "expiry_date": "2028-01-15",
          "gender": "MALE",
          "country": "SMP",
          "document_type": "ID",
          "nationality": "SMP",
          "full_name": "MOHAMMED AHMED ALI",
          "mrz_text": "IDSMP12345678<<8<<<<<<<<<<<<<<<9005205M28011520SMP<<<<<<<<<<<8MOHAMMED<AHMED<ALI<<<<<<",
          "document_no": "12345678"
        }
      },
      "metadata": {
        "device_ipv6": "fe80::dummy:ipv6:address",
        "gender": "MALE",
        "timestamp": "2025-02-04 08:30:00",
        "location": {
          "longitude": 55.123456,
          "latitude": 25.654321
        },
        "system_name": "Android",
        "system_version": "12.0.1",
        "device_identifier": "Samsung Galaxy S21",
        "extra_data": {
          "email": "[email protected]",
          "last_name": "Doe",
          "first_name": "John"
        },
        "device_type": "Smartphone",
        "device_ipv4": "192.168.1.100"
      },
      "artifacts": {
        "back_side_image": "https://xxxxx.yyyyy/back.png",
        "ocr_face_image": "https://xxxxx.yyyyy/face.png",
        "nfc_face_image": "https://xxxxx.yyyyy/nfc_face.png",
        "livness_image_without_bg": "https://xxxxx.yyyyy/liveness.png",
        "front_side_image": "https://xxxxx.yyyyy/front.png"
      },
      "type": {
        "title": "Sample ID",
        "value": 1
      },
      "status": {
        "title": "Successful",
        "value": 1
      }
    },
    "consolidated_message": "Verification retrieved successfully."
  }
}

Example Response for International Passport:

{
  "data": {
    "id": "abcd1234",
    "created_at": "2025-01-14T09:44:39.051016+00:00",
    "updated_at": "2025-01-14T09:45:33.344098+00:00",
    "updated_by": null,
    "data": {
      "NFC": {
        "name": "John Doe",
        "gender": "FEMALE",
        "address": "123 Elm Street",
        "nationality": "USA",
        "phone_number": "97987201",
        "document_type": "Passport",
        "name_of_holder": "John Doe",
        "place_of_birth": "City A",
        "document_number": "PL9087683",
        "issuing_country": "USA",
        "issuing_authority": "ABC",
        "document_expiry_date": "2030-03-18",
        "passport_date_of_birth": "1990-05-11"
      },
      "scan": {
        "gender": "Male",
        "country": "USA",
        "mrz_text": "MRZ123456",
        "full_name": "John Doe",
        "document_no": "DOC12345",
        "nationality": "American",
        "date_of_birth": "1990-05-15",
        "document_type": "Passport",
        "expiry_date": "2030-01-01"
      },
      "liveness": {
        "passive_liveness_confirmed": false,
        "active_liveness_confirmed": true
      }
    },
    "metadata": {
      "gender": "Female",
      "location": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "timestamp": "2024-58-22 08:58:52",
      "app_version": "1.0(11)",
      "device_ipv4": "0.0.0.0",
      "device_ipv6": "fe80::4cc0:34ff:fe60:cc21",
      "device_type": "SM-G996B",
      "system_name": "Android",
      "system_version": "13",
      "device_identifier": "samsung_SM-G996B"
    },
    "artifacts": {
      "nfc_face_image": "https://xxxxx.yyyyy/xxx.png",
      "ocr_face_image": "https://xxxxx.yyyyy/yyy.png",
      "back_side_image": "https://xxxxx.yyyyy/zzz.png",
      "front_side_image": "https://xxxxx.yyyyy/aaaa.png",
      "active_liveness_image": "https://xxxxx.yyyyy/xxx.png",
      "pasive_liveness_image": "https://xxxxx.yyyyy/abcd.png"
    },
    "annotations": {
      "face_matching": {
        "mode": "ocr",
        "notes": "",
        "is_successful": false,
        "matching_score": 40,
        "threshold_used": 53,
        "nfc_matching_score": null,
        "ocr_matching_score": 40
      }
    },
    "type": {
      "value": 2,
      "title": "International Passport"
    },
    "status": {
      "value": 1,
      "title": "Successful"
    }
  },
  "message": "Verification retrieved successfully.",
  "consolidated_message": "Verification retrieved successfully.",
  "details": {}
}