nashid_verify_sdk 2.6.5

The nashid_verify_sdk Flutter plugin provides an interface to integrate the Nashid SDK into your application for document scanning and verification purposes.

Flutter Implementation for Nashid Verification SDK (iOS & Android)

Introduction

This document serves as a comprehensive guide for Flutter 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.

The VerifySDK is designed to streamline identity verification processes, ensuring a smooth integration experience across platforms.

---

Prerequisites

• Prerequisites:
  • Latest Flutter SDK.
  • Latest CocoaPods for iOS.
  • Latest Android Studio with SDK tools.
  • Xcode (16.1 or higher) for iOS development.
  • iOS 16.0 or higher
  • An IDE like Android Studio or VS Code with Flutter and Dart plugins.
  • Gradle 8.12.0+ (required to avoid Android 16KB page size DEX issues with large dependencies)
• Recommendations:
  • We recommend that you run flutter doctor to verify the setup.
  • We recommend that you set up a real-device for testing.
  • We recommend that you run flutter pub get to fetch plugin dependencies.

---

Installation

1. Run this command:

   flutter pub add nashid_verify_sdk
   

   Note: Alternatively, you can update your pubspec.yaml manually to include the package as the following:

   dependencies:
     nashid_verify_sdk: ^latest_version
   

2. For iOS, Do the following:

   a. In iOS module’s 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>
   

   b. In Podfile:

   # Update iOS deployment target
   platform :ios, '16.0'
         
         
         
   post_install do |installer|
      installer.pods_project.targets.each do |target|
        flutter_additional_ios_build_settings(target)
     
         # --- Add these Lines ---
        target.build_configurations.each do |config|
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
        # -------------------------
     
      end
   end
   

   c. 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.

   d. Add the following lines to your ios/Runner/Runner.entitlements file if your app uses both general NFC and ISO7816-based scanning:

   <key>com.apple.developer.nfc.readersession.formats</key>
   <array>
     <string>TAG</string>
     <!-- Add ISO7816 only if your app uses both general NFC and ISO7816-based scanning -->
     <string>ISO7816</string> 
   </array>
   

   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. Add the following script in Build Phases > Run Script and ensure that this script is always the last step in the list.

   cd "${CONFIGURATION_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/Frameworks/VerifySDK.ramework/"
   if [[ -d "Frameworks" ]]; then
   rm -fr Frameworks
   fi
   

   g. Run:

   cd ios && pod install
   

3. For Android, Do the following:

   a. Update Gradle Version:

   Ensure your Android Gradle Plugin version is 8.12.0 or higher in android/build.gradle (project-level) or android/settings.gradle if your version is specified there.

   Check your android/gradle/wrapper/gradle-wrapper.properties file and ensure it has:

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.12-all.zip
   

   Why? Gradle 8.12.0+ is required to avoid Android 16KB page size DEX issues when using large dependencies.

   Need a different version? Find all available Gradle versions at: Gradle Releases

   b. Update AndroidManifest.xml:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:tools="http://schemas.android.com/tools"> <!--Add this line in manifest tag-->
         
   <!-- Add this attribute to the <application> tag -->
   tools:replace="android:name"
   android:enableOnBackInvokedCallback="true"
   

   c. Recommendation to use the following lines to app-level build.gradle file:

   android {
     compileSdk 36
     defaultConfig {
       minSdk 21
       targetSdk 36
   }
   

Usage

1. Import Nashid Verify SDK:

// Import this package to access all the required functions
import 'package:nashid_verify_sdk/nashid_verify_sdk.dart';

2. Initialize Nashid Verify 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:

1. SDK Application Key (Mandatory): The key generated using your Nashid Verify admin dashboard.
2. SDK Application Key Secret (Mandatory): The key secret generated using your Nashid Verify admin dashboard.
3. Language Code (Optional): en for English (default), ar for Arabic ..etc.
4. 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.

// Create an instance to access the SDK functions
final _nashidIoPlugin = NashidVerifySdk();

Map<String, dynamic> response = await _nashidIoPlugin.initialize(
    sdkKey: "<your-sdk-key>",
    sdkSecretKey: "<your-sdk-secret-key>",
    languageId:"en",
    extraData: {
       "example-key": "example-values",
    }
);

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 Flutter app UI. How to use:

final subscription = _nashidIoPlugin.exitEvents.listen((event) {
  // event will be one of: 'OcrCancelled', 'NfcCancelled', 'LivenessCancelled' or 'Completed'
  if (event == 'OcrCancelled') {
    // Handle document scanning cancellation
  } else if (event == 'NfcCancelled') {
    // Handle NFC scanning cancellation
  } else if (event == 'LivenessCancelled') {
    // Handle liveness check cancellation
  } else if (event == 'MalaConsentDeclined') {
    // Handle mala consent declined check cancellation
  } else if (event == 'Completed') {
    // Handle successful completion
  }
});
// To stop listening:
// subscription.cancel();

Note:

• Always cancel the subscription when you no longer need to listen (e.g., in dispose).

---

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 expects an input argument specifying the type of document to be verified using the NashidDocumentType enum.

ID Type	Enum Value
OMANI_ID	NashidDocumentType.OMANI_ID
INTERNATIONAL_PASSPORT	NashidDocumentType.INTERNATIONAL_PASSPORT
EMIRATI_ID	NashidDocumentType.EMIRATI_ID
SAUDI_ID	NashidDocumentType.SAUDI_ID
BAHRAINI_ID	NashidDocumentType.BAHRAINI_ID
QATARI_ID	NashidDocumentType.QATARI_ID
KUWAITI_ID	NashidDocumentType.KUWAITI_ID

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

1. Result: A boolean flag that is true when the verification flow is successful, and false other wise.
2. Error Message: A string contains the error details in case of unsuccessful verification.
3. 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.

Example1: Verify With Omani ID

Map<String, dynamic> response = await _nashidIoPlugin.verify(ofType: NashidDocumentType.OMANI_ID);

Example2: Verify With International Passport

Map<String, dynamic> response = await _nashidIoPlugin.verify(ofType: NashidDocumentType.INTERNATIONAL_PASSPORT);

Example3: Verify With Emirati ID

Map<String, dynamic> response = await _nashidIoPlugin.verify(ofType: NashidDocumentType.EMIRATI_ID);

Example4: Verify With Saudi ID

Map<String, dynamic> response = await _nashidIoPlugin.verify(ofType: NashidDocumentType.SAUDI_ID);

Example5: Verify With Bahraini ID

Map<String, dynamic> response = await _nashidIoPlugin.verify(ofType: NashidDocumentType.BAHRAINI_ID);

Example6: Verify With Qatari ID

Map<String, dynamic> response = await _nashidIoPlugin.verify(ofType: NashidDocumentType.QATARI_ID);

Example7: Verify With Kuwait ID

Map<String, dynamic> response = await _nashidIoPlugin.verify(ofType: NashidDocumentType.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 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

Map<String, dynamic> response = await _nashidIoPlugin.getVerificationResult(
verificationId: "abcd1234",
);

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

{
    "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"
            },
            "barcode": {
                "id_number": "26863400752",
                "serial_number": "01111112321312",
             },
            "liveness": {
                "score": "99",
                "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
            }
        },
        "type": {
            "value": 2,
            "title": "International Passport"
        },
        "status": {
            "value": 3,
            "title": "Verified"
        }
    },
    "message": "Verification retrieved successfully.",
    "consolidated_message": "Verification retrieved successfully.",
    "details": {}
}

The status field represents the current state of the verification process. It is returned as an object:

"status": {
  "value": <integer>,
  "title": <string>
}

Possible Status Values

Value	Title	Description
1	Data not collected	One or more verification steps based on the configured functionality did not complete successfully within allowed attempts or retries.
2	Data collected	All configured verification steps were completed successfully, but final evaluation against the selected verification criteria is still pending.
3	Verified	All verification criteria (default or custom) were successfully met. This may include checks like data collection, face match, or liveness—depending on setup.
4	Not verified	One or more verification criteria (default or custom) were not met. This may include checks like data collection, face match, or liveness—depending on setup.
5	Processing	Initial verification data has been successfully collected, and the backend is still processing the results.