Flutter SDK | Vlens | Documentation

The Vlens Flutter SDK (vlens) embeds the full identity verification experience — national ID scanning, liveness detection, and face matching — directly into your mobile app with a single method call.

pub.dev

vlens · v0.1.9

Android

API 21+, Dart SDK ≥ 3.6

iOS

iOS 13+, Dart SDK ≥ 3.6

Installation

Add the SDK to your pubspec.yaml:

1 dependencies:
2   vlens: ^0.1.9

Then fetch dependencies:

$ flutter pub get

Android setup

For Android 13+, add the following attribute to the <application> tag in android/app/src/main/AndroidManifest.xml:

1 <application
2   android:enableOnBackInvokedCallback="false"
3   ...>

Omitting this attribute on Android 13+ causes back navigation to behave incorrectly inside the SDK screens.

Quick start

Import the package and call VLensManager().init() with a configured SdkConfig:

1 import 'package:vlens/vlens.dart';
2 
3 VLensManager().init(context, sdkConfig);

That one call launches the full verification UI. The SDK handles camera permissions, ID scanning, liveness detection, and result delivery through your callbacks.

Configuration

`EnvironmentConfig`

Connects the SDK to your Vlens tenant:

1 EnvironmentConfig(
2   apiBaseUrl: "https://api.vlenseg.com",
3   accessToken: "USER_ACCESS_TOKEN",   // from registration/login
4   refreshToken: "USER_REFRESH_TOKEN",
5   apiKey: "YOUR_API_KEY",
6   tenancyName: "YOUR_TENANT",
7 )

Parameter	Description
`apiBaseUrl`	Vlens API base URL
`accessToken`	User JWT from registration or login
`refreshToken`	Token used to refresh the access token
`apiKey`	Your tenant API key
`tenancyName`	Your tenant name

`ColorsConfig`

Customise the SDK UI to match your brand — supports separate light and dark themes:

1 colors: ColorsConfig(
2   light: ColorConfig(
3     accent: "#4E5A78",
4     primary: "#397374",
5     secondary: "#FF4081",
6     background: "#FEFEFE",
7     dark: "#000000",
8     light: "#FFFFFF",
9   ),
10   dark: ColorConfig(
11     accent: "#FFC107",
12     primary: "#2196F3",
13     secondary: "#FF4081",
14     background: "#000000",
15     dark: "#FFFFFF",
16     light: "#000000",
17   ),
18 ),

`SdkConfig` — all parameters

Parameter	Type	Default	Description
`transactionId`	`String`	—	Transaction ID to use or resume
`env`	`EnvironmentConfig`	—	API credentials and endpoint
`isLivenessOnly`	`bool`	`false`	Skip ID scanning — liveness only
`isNationalIdOnly`	`bool`	`false`	Skip liveness — ID scan only
`getExtractedData`	`bool`	`false`	Return OCR-extracted fields in `onSuccess`
`defaultLocale`	`String`	`"en"`	UI language — `"en"` or `"ar"`
`logoPath`	`String`	—	Asset path to your logo image
`colors`	`ColorsConfig`	—	Light and dark theme colours
`detectionRetryCounter`	`int`	`5`	Number of liveness retries before failure
`disableAutoCapture`	`bool`	`false`	Require manual capture instead of auto-capture
`enableSounds`	`bool`	`false`	Play audio feedback during scanning
`errorMessages`	`List<ApiError>`	`[]`	Override default error messages
`onSuccess`	`Function(ExtractData?)`	—	Called when verification succeeds
`onFailure`	`Function(String, String)`	—	Called with `(errorCode, errorMessage)` on failure

Verification modes

Full verification (default)

Liveness only

ID scan only

Runs the complete flow: ID front → ID back → liveness.

1 final sdkConfig = SdkConfig(
2   transactionId: transactionId,
3   isLivenessOnly: false,
4   isNationalIdOnly: false,
5   getExtractedData: true,
6   env: EnvironmentConfig(
7     apiBaseUrl: "https://api.vlenseg.com",
8     accessToken: userAccessToken,
9     refreshToken: userRefreshToken,
10     apiKey: apiKey,
11     tenancyName: tenantName,
12   ),
13   defaultLocale: "ar",
14   logoPath: "assets/images/logo.png",
15   enableSounds: true,
16   colors: ColorsConfig(
17     light: ColorConfig(
18       primary: "#397374",
19       accent: "#4E5A78",
20       background: "#FEFEFE",
21       dark: "#000000",
22       light: "#FFFFFF",
23       secondary: "#FF4081",
24     ),
25     dark: ColorConfig(
26       primary: "#2196F3",
27       accent: "#FFC107",
28       background: "#000000",
29       dark: "#FFFFFF",
30       light: "#000000",
31       secondary: "#FF4081",
32     ),
33   ),
34   onSuccess: (extractedData) {
35     print("Verified: ${extractedData?.idFrontData?.name}");
36   },
37   onFailure: (errorCode, errorMsg) {
38     print("Failed [$errorCode]: $errorMsg");
39   },
40 );
41 
42 VLensManager().init(context, sdkConfig);

Handling results

`onSuccess` — `ExtractData`

When verification succeeds, onSuccess is called with an ExtractData object (if getExtractedData: true):

1 onSuccess: (ExtractData? extractedData) {
2   // User profile
3   final user = extractedData?.user;
4   print(user?.fullName);
5   print(user?.phoneNumber);
6   print(user?.emailAddress);
7   print(user?.idNumber);
8 
9   // ID front data
10   final front = extractedData?.idFrontData;
11   print(front?.name);           // Arabic full name
12   print(front?.name_english);   // Transliterated name
13   print(front?.idNumber);
14   print(front?.dateOfBirth);
15   print(front?.gender);
16   print(front?.govern);         // Governorate
17 
18   // ID back data
19   final back = extractedData?.idBackData;
20   print(back?.maritalStatus);
21   print(back?.job);
22   print(back?.religion);
23   print(back?.idExpiry);
24 
25   // Verification status
26   print(extractedData?.isDigitalIdentityVerified);
27 },

`onFailure`

Called with (errorCode, errorMessage) when verification fails or the user cancels:

1 onFailure: (String errorCode, String errorMsg) {
2   // Show error to user or log for debugging
3   ScaffoldMessenger.of(context).showSnackBar(
4     SnackBar(content: Text(errorMsg)),
5   );
6 },

Custom error messages

Override specific error messages to match your app’s tone or language:

1 errorMessages: [
2   ApiError(
3     errorCode: 101,
4     errorMessageEn: "Network error. Please check your connection.",
5     errorMessageAr: "خطأ في الشبكة. يرجى التحقق من الاتصال.",
6   ),
7 ],

Relation to the REST API

The SDK wraps the same REST endpoints documented in the Digital Identity guide:

SDK action	REST endpoint
Full flow	`verify/id/front` → `verify/id/back` → `verify/liveness/multi`
Liveness only	`verify/liveness/multi`
ID scan only	`verify/id/front` → `verify/id/back`

The transactionId in SdkConfig maps to transaction_id in the REST API — pass the same value to link SDK results with server-side records.

Latest version

v0.1.9 — UI improvements: primary color applied to ID frames and scanning GIFs, sticky buttons on ID review screen, improved status indicator messages during camera capture, enhanced localisation.

See all versions on pub.dev/packages/vlens/versions.