VLens Flutter SDK Documentation #

Overview #

VLens Flutter SDK provides seamless integration for biometric verification and identity scanning in your Flutter applications. This SDK supports National ID scanning and liveness detection.

Installation #

To install VLens, add the following dependency to your pubspec.yaml file:

dependencies:
  vlens: latest_version

Run the following command to fetch the package:

flutter pub get

Usage #

Import the Package #

import 'package:vlens/vlens.dart';

Initialize the SDK #

To initialize VLens, configure the SDK settings and call VLensManager().init().

final sdkConfig = SdkConfig(
  transactionId: 'your_transaction_id',
  isLivenessOnly: false,
  isNationalIdOnly: false,
  logoPath: "your_asset_path",  
  env: EnvironmentConfig(
    apiBaseUrl: "https://api.vlenseg.com",
    accessToken: "your_access_token",
    refreshToken: "your_refresh_token",
    apiKey: "your_api_key",
    tenancyName: "your_tenancy_name",
  ),
  defaultLocale: "en",
  colors: ColorsConfig(
    light: ColorConfig(
      accent: "#4E5A78",
      primary: "#397374",
      secondary: "#FF4081",
      background: "#FEFEFE",
      dark: "#000000",
      light: "#FFFFFF",
    ),
    dark: ColorConfig(
      accent: "#FFC107",
      primary: "#2196F3",
      secondary: "#FF4081",
      background: "#000000",
      dark: "#FFFFFF",
      light: "#000000",
    ),
  ),
  errorMessages: [
    ApiError(
      errorCode: 101,
      errorMessageEn: "Network error",
      errorMessageAr: "\u062E\u0637\u0623 \u0641\u064A \u0627\u0644\u0634\u0628\u0643\u0629",
    ),
  ],
  onSuccess: (extractedData) {
    // Handle success
    Logger().d("verification success ${extractedData?.idFrontData?.name}");
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text("Success Verified!")),
    );
  },
  onFailure: (String errorCode, String errorMsg) {
    // Handle failure
    Logger().d("Main verification failed due to: $errorMsg, Code: $errorCode");
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(errorMsg)),
    );
  },
  detectionRetryCounter: 5,
  getExtractedData: true,
  disableAutoCapture: false
);

VLensManager().init(context, sdkConfig);

To make it work on Android 13 and up, set this to false in the Android manifest:

android:enableOnBackInvokedCallback="false"

Example Project #

import 'package:flutter/material.dart';
import 'package:vlens/vlens.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'VLens Flutter SDK Demo',
      home: const VLensDemoScreen(),
    );
  }
}

class VLensDemoScreen extends StatefulWidget {
  const VLensDemoScreen({super.key});

  @override
  State<VLensDemoScreen> createState() => _VLensDemoScreenState();
}

class _VLensDemoScreenState extends State<VLensDemoScreen> {
  final TextEditingController _transactionIdController = TextEditingController();
  final TextEditingController _accessTokenController = TextEditingController();
  bool _isDataComplete = false;

  void _getStarted() {
    final sdkConfig = SdkConfig(
      transactionId: _transactionIdController.text,
      isLivenessOnly: false,
      isNationalIdOnly: false,
      logoPath: "your_asset_path",
      env: EnvironmentConfig(
        apiBaseUrl: "https://api.vlenseg.com",
        accessToken: _accessTokenController.text,
        refreshToken: "your-refresh-token",
        apiKey: "your-api-key",
        tenancyName: "your-tenancy-name",
      ),
      defaultLocale: "en",
      colors: ColorsConfig(
        light: ColorConfig(
          accent: "#4E5A78",
          primary: "#397374",
          secondary: "#FF4081",
          background: "#FEFEFE",
          dark: "#000000",
          light: "#FFFFFF",
        ),
        dark: ColorConfig(
          accent: "#FFC107",
          primary: "#2196F3",
          secondary: "#FF4081",
          background: "#000000",
          dark: "#FFFFFF",
          light: "#000000",
        ),
      ),
      errorMessages: [
        ApiError(
          errorCode: 101,
          errorMessageEn: "Network error",
          errorMessageAr: "خطأ في الشبكة",
        ),
      ],
      onSuccess: (extractedData) {
        // Handle success
        Logger().d("verification success ${extractedData?.idFrontData?.name}");
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(content: Text("Success Verified!")),
        );
      },
      onFailure: (String errorCode, String errorMsg) {
        // Handle failure
        Logger().d("Main verification failed due to: $errorMsg, Code: $errorCode");
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text(errorMsg)),
        );
      },
      detectionRetryCounter: 5,
      getExtractedData: true,
      disableAutoCapture: false
    );
    VLensManager().init(context, sdkConfig);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('VLens Flutter SDK Demo')),
      body: Center(
        child: ElevatedButton(
          onPressed: _isDataComplete ? _getStarted : null,
          child: const Text('Get Started'),
        ),
      ),
    );
  }
}

Configuration Options #

SdkConfig #

• transactionId (String): Unique identifier for the transaction.
• isLivenessOnly (Boolean): Enables or disables liveness detection mode.
• isNationalIdOnly (Boolean): Enables or disables national ID scanning mode.
• logoPath (String?): Path to the logo image.
  • Example: "assets/images/your_logo_name.png".
  • Default value : VLens logo.
• env (EnvironmentConfig): Contains API-related configurations.
  • apiBaseUrl (String): Base URL for the VLens API.
  • accessToken (String): Access token for authentication.
  • refreshToken (String): Token for refreshing access when expired.
  • apiKey (String): API key for the VLens service.
  • tenancyName (String): Name of the tenant using the service.
• defaultLocale (String): Specifies the default language (e.g., "en" for English, "ar" for Arabic).
• colors (Colors): Theming configuration for light and dark modes.
  • light (ColorConfig): Color palette for light mode.
  • dark (ColorConfig): Color palette for dark mode.
• errorMessages (List: Custom error messages.
  • errorCode (Int): Error code returned from the API.
  • errorMessageEn (String): Error message in English.
  • errorMessageAr (String): Error message in Arabic.
• retryCounter (Int): Specifies the number of allowed retries for detection before failing.
  • default value is = 5
• getExtractedData (Boolean): If true, the SDK will return extracted data after successful scanning.
• disableAutoCapture (Boolean): If true, the sdk will disable the auto capture for national id front and back (default value false).
• onSuccess ((extractedData) -> {}): Lambda triggered when the initialization succeeds. Returns an extractData object.
• onFailure ((errorCode, errorMsg) -> {}): Lambda triggered when the initialization fails. Returns an error code and error message.

ExtractData #

• isDigitalIdentityVerified: Boolean

• isVerificationProcessCompleted: Boolean

• deviceInfo: String

• user: {
    - id: Int
    - name: String
    - surname: String
    - fullName: String
    - userName: String
    - emailAddress: String
    - phoneNumber: String
    - idNumber: String
    - address: String
  }

• idFrontData: {
    - nameEnglish: String
    - firstNameEnglish: String
    - lastNamesEnglish: String
    - name: String
    - address: String
    - firstName: String
    - lastName: String
    - govern: String
    - idKey: String
    - address1: String
    - address2: String
    - addressEnglish: String
    - address1English: String
    - address2English: String
    - governEnglish: String
    - city: String
    - district: String
    - dateOfBirth: String
    - idNumber: String
    - gender: String
    - clientTransactionId: String
    - requestId: String
    - transactionId: String
  }
  

• idBackData: {
    - maritalStatus: String
    - job: String
    - jobTitle: String
    - religion: String
    - husbandName: String
    - releaseDate: String
    - idExpiry: String
    - maritalStatusEnglish: String
    - religionEnglish: String
    - genderEnglish: String
    - husbandNameEnglish: String
    - jobEnglish: String
    - jobTitleEnglish: String
    - idNumber: String
    - gender: String
    - clientTransactionId: String
    - requestId: String
    - transactionId: String
  }

Error Handling #

Define custom error messages using ApiError:

ApiError(
  errorCode: 101,
  errorMessageEn: "Network error",
  errorMessageAr: "\u062E\u0637\u0623 \u0641\u064A \u0627\u0644\u0634\u0628\u0643\u0629",
);

Support #

For questions and support, contact the VLens team at support@vlens.com.