verification_sdk 1.2.2

Flutter SDK for multi-stage identity verification with camera, webview and KYC flows for mobile and web apps.

verification_sdk

Flutter SDK for multi-stage identity verification (mobile OTP, DigiLocker Aadhaar fetch, face-match). Drop-in UI, hosted flows, and host callbacks for integration.

Quick start

1. Add the package (local or from pub.dev):

   dependencies:
       verification_sdk: ^1.2.2
   

2. Initialize the SDK once (before first use):

   import 'package:verification_sdk/verification_sdk.dart';
   
   await VerificationSDK.initialize(
       clientId: 'YOUR_CLIENT_ID',
       sessionToken: 'YOUR_SESSION_TOKEN',
       environment: Environment.sandbox,
       userData: {
           'mobileNumber': '9123456789',
           'brandLogoUrl': 'https://example.com/logo.png',
           'brandTitle': 'Acme Inc.',
           'primaryColor': '#1E88E5',
       },
   );
   

3. Launch the verification flow from any BuildContext:

   VerificationSDK.startVerification(context,
       callbacks: VerificationCallbacks(
           onStageComplete: (stage) => debugPrint('stage: $stage'),
           onError: (err) => debugPrint('sdk error: $err'),
           onComplete: (result) => debugPrint('sdk complete: $result'),
       ),
   );
   

Initialization options

• Required:
  • clientId (string)
  • sessionToken (string)
  • environment (Environment.sandbox | Environment.production)
• Optional userData keys:
  • mobileNumber — prefill mobile (string)
  • brandLogoUrl — header logo (string: URL)
  • brandTitle — optional title (string)
  • primaryColor — overrides SDK primary color (accepted formats):
    • integer: 0xAARRGGBB (e.g. 0xFF1E88E5)
    • hex string: "#RRGGBB", "RRGGBB" (alpha assumed FF)
    • hex string with alpha: "AARRGGBB"

Platform setup

Android

• Add to android/app/src/main/AndroidManifest.xml:
  • <uses-permission android:name="android.permission.CAMERA"/>
  • <uses-permission android:name="android.permission.INTERNET"/>
• Ensure WebView is available/updated on target devices (Digilocker uses WebView).

iOS

• Add to ios/Runner/Info.plist:
  • NSCameraUsageDescription — explanation for camera access.
• Ensure App Transport Security allows required endpoints (HTTPS recommended).

Permissions are requested at runtime where required.

What the SDK does (integrator view)

• Presents a bottom-sheet flow above your app to:
  • Send OTP and verify mobile
  • Fetch Aadhaar XML from DigiLocker (WebView OIDC)
  • Capture a front-camera selfie and run face-match against Aadhaar photo
    • Selfie is uploaded to a presigned URL (S3-style) and the resulting public image2_url is sent to the face-match API (server contract).
• Returns progress events and final result via VerificationCallbacks:
  • onStageComplete(Map) — stage-level progress (see fields below)
  • onStageStarted(Map) — optional stage-started signal (new in v1.1.x)
  • onError(String) — errors
  • onComplete(Map) — final result when SDK closes

Callback details (what host receives)

• onStageComplete payloads include stage-specific fields. Notable additions in v1.1.1:
  • For Aadhaar OCR stage:
    • aadhaar_front_path — local file path to the saved front image (if available)
    • aadhaar_back_path — local file path to the saved back image (if available)
    • aadhaar_front_base64 — optional base64 (present when encoding succeeds)
    • aadhaar_back_base64 — optional base64 (present when encoding succeeds)
    • results — OCR API responses for front/back (aadhaar_ocr_front, aadhaar_ocr_back)
  • For Face Match:
    • match — numeric match percentage (normalized double)
    • selfie_path — local selfie path
    • selfie_base64 — optional base64 (present when encoding succeeds)
    • status — success or failed
  • Error payloads: when APIs return structured errors, SDK surfaces them in onError and onStageComplete (with status: failed and error detail fields).
• Note: selfie_base64 can be large; host apps should avoid insecure logging or persistent storage of base64 image strings.

Presigned upload & face-match contract

• The SDK requests a presigned URL from the server (/verify/s3/presign_url) for selfie uploads.
• It supports both POST-form presigns (with fields) and PUT-style presigns (with headers).
• After a successful upload, the SDK calls /verify/face_match with:
  • image1 — Aadhaar file (multipart file)
  • image2_url — public URL of the uploaded selfie (string)
• Ensure your backend returns a usable presign url and fields/headers as appropriate.

Theming & Branding

• Use userData['brandLogoUrl'] to show your logo in the header.
• Override UI accent with primaryColor described above.

Testing & debugging

• Test on a physical device for camera and WebView behavior.
• SDK logs face-match request/response details to the Flutter console to aid debugging (token preview, file paths, sizes, server response). Remove or filter these logs in production.
• Typical failure modes:
  • Camera permission denied — user must grant camera access.
  • Presign upload issues — server must provide correct presign fields/headers.
  • WebView renderer crashes on some emulators — verify on a physical device.
• Face-match preview rendering: the SDK forces the camera preview and captured image to a 260×260 square so ClipOval renders a true circle and avoids oval viewfinders on devices with differing aspect ratios.

Version notes

• v1.1.2 — 2026-01-24
  • Fixed viewfinder rendering: camera preview and captured selfie are constrained to a 260×260 square so the circular viewfinder is always a true circle.
  • Face-match callbacks now guarantee selfie_path on success; selfie_base64 remains optional and is included only when encoding succeeds.
  • Clarified README and testing notes about preview sizing and base64 handling.
• v1.1.1:
  • Selfie upload → presign URL flow for face-match.
  • Aadhaar OCR callbacks now include file paths and optional base64 payloads.
  • Fail-fast error handling and improved stage lifecycle events.

Example (local example app)

An example app is included in example that demonstrates:

• VerificationSDK.initialize(...)
• VerificationSDK.startVerification(...) usage

Run it:

cd example
flutter pub get
flutter run

Support & contact

For integration questions, provide:

• Client ID and environment details (sandbox vs production)
• Example sessionToken acquisition method (server-side)
• Any custom navigator or host-app constraints