Skip to content
BranchesTags

Repository files navigation

FacePlugin

🌐 Company Site - Here

🤗 Hugging Face - Here

🛟 Help Center - Here

🐳 Docker Hub - Here

FacePlugin ID Document Recognition SDK — Ionic Capacitor (Fully On-Premise)

Drop Android AAR + iOS framework → Sync Capacitor → run on a physical phone. Jump: Quick Start · Get the runtimes · Run the demo · Setup · JS API

Quick Start

  • Install Node.js 18+ (includes npm)
  • Install JDK 17
  • Install Android Studio (Android) or Xcode 15+ (iOS, macOS only)
  • git clone https://github.com/Faceplugin-ltd/ID-Document-Recognition-Ionic-Capacitor.git
  • cd ID-Document-Recognition-Ionic-Capacitor
  • npm install
  • npm run build
  • cd example && npm install
  • Download runtimes → Get the runtimes
  • Copy documentreadersdk.aar → example/android/libdocsdk/
  • Copy docsdk.framework → ios/Frameworks/docsdk.framework (iOS)
  • npm run build
  • npx cap sync
  • npx cap open android or npx cap open ios
  • Run on a physical phone from Android Studio / Xcode
  • Home status bar → Ready → Camera / Gallery / About

Own app? → Setup on your own app. Docs: https://doc.faceplugin.com

Introduction

FacePlugin ID Document Recognition SDK for Ionic Capacitor is a fully on-device identity verification plugin for Android and iOS. Scan ID cards, passports, and driver licenses with OCR, MRZ, barcode and QR extraction, live camera overlay, gallery front/back, authenticity / document liveness, and Result / Security / Images / Raw JSON. Package: document-reader-capacitor. No biometric data leaves the device — built for KYC and hybrid mobile onboarding.

Folder Purpose
Repository root document-reader-capacitor — Capacitor plugin you install in your Ionic app
example/ Ionic React demo (Home, Camera, Gallery, Result, About)

Native binaries are not on GitHub. Download them from Google Drive (links below).

Browser / ionic serve alone is not enough. Native Document Reader APIs require a Capacitor Android or iOS build on a device.

Main Functionalities

Feature Supported
ID Card, Passport, and Driver License recognition ✓
MRZ, Barcode, QR, and OCR data extraction ✓
Document detection and type classification ✓
Live camera locate overlay + Capture ✓
Gallery front / optional back ✓
Result (fields, Security, images, JSON) ✓
Authenticity / Security (document liveness) ✓

Product List

Platform Repository
Android ID-Document-Recognition-Android
iOS ID-Document-Recognition-iOS
Windows ID-Document-Recognition-Windows
Linux / Docker ID-Document-Recognition-Docker
React Native ID-Document-Recognition-React-Native
Flutter ID-Document-Recognition-Flutter
Ionic Capacitor ID-Document-Recognition-Ionic-Capacitor (this repo)
Ionic Cordova ID-Document-Recognition-Ionic-Cordova
Linux / Docker (Liveness) ID-Document-Liveness-Detection-Docker

Before you start

Step What you need
1 Node.js 18+, npm, Ionic / Capacitor
2 Physical device recommended (camera; emulator is limited)
3 Android documentreadersdk.aar and iOS docsdk.framework — Get the runtimes
4 Demo licenses are in example/src/license.ts (Android com.faceplugin.documentreader, iOS com.faceplugin.documentreader.app, valid until 12 August 2027). Request a new key only if you change applicationId / bundle id — SDK License

System requirements

Item Android iOS
OS API 24 min; API 29 (10)+ recommended 13.0 min; 16+ recommended
Device Physical phone with rear camera iPhone with A12 or newer
Stack Capacitor 6 + Ionic React (example/) Same
Build Android Studio / JDK 17 Xcode 15+, CocoaPods

Get the runtimes

Binaries are gitignored. Copy them before your first native build.

Android — documentreadersdk.aar

Download: DocumentReader Android runtime (Google Drive)

File Example app path Your own app path
documentreadersdk.aar example/android/libdocsdk/documentreadersdk.aar node_modules/document-reader-capacitor/android/libs/documentreadersdk.aar

iOS — docsdk.framework

Download: DocumentReader iOS runtime (Google Drive) — unzip if needed.

ios/Frameworks/docsdk.framework

Then npx cap sync ios / pod install. Framework is device arm64 only.

Run the demo

Follow these steps in order to run the demo.

1. Install tools on your computer

  1. Install Node.js 18 or newer from https://nodejs.org/ (choose the LTS version). This also installs npm.
  2. Open a terminal (PowerShell, Terminal, or Command Prompt) and check:
node -v
npm -v
  1. Install JDK 17 from https://adoptium.net/ (Temurin 17).
  2. Android: install Android Studio, open it once, and install the Android SDK + a device USB driver if needed.
  3. iOS (Mac only): install Xcode 15+ from the App Store, then open Xcode once and accept the license. Install CocoaPods if prompted (sudo gem install cocoapods).
  4. Plug in a physical phone and enable Developer / USB debugging (Android) or trust the computer (iPhone). Emulators are limited for camera.

2. Download this project

git clone https://github.com/Faceplugin-ltd/ID-Document-Recognition-Ionic-Capacitor.git
cd ID-Document-Recognition-Ionic-Capacitor

If you do not use Git, download the ZIP from GitHub → Code → Download ZIP, unzip it, and cd into the folder.

3. Install npm packages and build the plugin

From the repository root:

npm install
npm run build

Then install the example app:

cd example
npm install

4. Place the native runtimes

Download the binaries from Get the runtimes, then copy them exactly here:

Platform File Put it here
Android documentreadersdk.aar example/android/libdocsdk/documentreadersdk.aar
iOS docsdk.framework ios/Frameworks/docsdk.framework

Create the folders if they do not exist. Do not rename the files.

5. Build the web app and sync Capacitor

Still inside example/:

npm run build
npx cap sync

This copies the web build into the native Android / iOS projects and links the Capacitor plugin.

6. Open and run on your phone

Android

npx cap open android
  1. Android Studio opens the example/android project.
  2. Wait until Gradle finishes syncing.
  3. Choose your USB phone in the device list.
  4. Press the green Run button.

iOS (macOS only)

npx cap open ios
  1. Xcode opens the workspace.
  2. Select your Team under Signing & Capabilities.
  3. Choose your physical iPhone (not a simulator).
  4. Press Run.

docsdk.framework is device-only (arm64). Simulator builds may compile, but the engine will not activate on a simulator.

Keep these demo app ids so the included license works:

Platform Identifier
Android applicationId com.faceplugin.documentreader
iOS bundle id com.faceplugin.documentreader.app

7. Use the demo

  1. Wait for the home status bar → Ready.
  2. Camera — live rear preview with document locate overlay → Capture → on-device OCR, MRZ, barcode, and authenticity checks.
  3. Gallery — pick front (back optional) → recognize two-sided IDs.
  4. Result — tabs Result / Security / Images / Raw JSON for fields, liveness, crops, and the full JSON response.

Screenshots

Home Camera Gallery

FacePlugin Document Reader — Home with Camera, Gallery, About and Recognition + Liveness

FacePlugin Document Reader — live camera overlay and Capture for ID scanning

FacePlugin Document Reader — Gallery front and optional back, then Recognize
Result Security Images

FacePlugin Document Reader — Result tab with OCR, MRZ, and barcode fields

FacePlugin Document Reader — Security tab with authenticity and document liveness

FacePlugin Document Reader — Images tab with portrait, signature, and document crops
Raw JSON About

FacePlugin Document Reader — Raw JSON recognize response for integration

FacePlugin Document Reader — About with on-device Recognition + Liveness license

SDK License

Licenses are offline and bound to your applicationId / bundle identifier.

The sample app already includes a valid key for com.faceplugin.documentreader (Android) / com.faceplugin.documentreader.app (iOS) (until 12 August 2027). You only need a new key if you use a different id.

How to get a license

The code below shows how to use the license:

ID-Document-Recognition-Ionic-Capacitor/example/src/license.ts

Lines 7 to 17 in d9f1fea

/** Android demo applicationId (capacitor.config.ts appId) */
export const ANDROID_APPLICATION_ID = 'com.faceplugin.documentreader';
/** iOS demo bundle id (set in Xcode / project.pbxproj) */
export const IOS_BUNDLE_ID = 'com.faceplugin.documentreader.app';
const ANDROID_LICENSE =
'FP1.RlBMMQMAAQBf3SxYY7bhQfhFFCEPAgAA3/iiRUGiXouaIYrntAmVD2wPeZTesqNc17RCMDyrl0QXCrHcGv3VpADVrxXu+HxhfNtTQFc80m7qZPLtkbRsUvzPnwXiga2STv5ECokcY0Mx8R+9NqtKMK8cUITUVts/0hBW9053jyNsMV5n+hxYlwpG97BvdDJpRBjhgWhpuqdGCm2FnxMZgYOOsVQiLUHjxiOlls2af4UUTNXSedPF0+F1pxTfAQqmvGkx1KTSu63tgTNIH6wybdw58pAyWbFX515ZGSjgM41G6FfOSykLNZYvxFeiRw2KIDMZxImqKCGGQ5nv3L3z8p0PRQLKTcMSasOIw5V2PuHwtXNoM8CHOT9Lltyzx6vAaV9eqwEpu2HfPl29jK/uXNMHpTeP1IVHzVIUwfC9htJ53B34HGOTeFEAw9tMQ9XpEvU35hi907KetbMbUGB55uokAZZU3nOWCbfeacsSy66xJ+hAJKFGdcGSuRIcRaEDfwIZJjuOQrtsCk9SDkBVesNygvOeQ1qm0M5EmMRld6A26eTpuD7iAs/dY0ixgcAPHWPpy0q0Sh/Kq1cO1/yOxhNOmRSYPnH2qkboqZdJdjD8lOUGar3IYt493iL633qK50cLvrvWvbPM+CbLnQPM80/eXIG/HGqnxabNBEjm+Fl9O0OEsJ6xSpPDZ7CaT/aLxpFJ8TVPV9/kijz1LdPpPDj3yk+JtbuLADCBiAJCAVszoGvhFpKEgLztY4qAH4uM0hkW3H8vTgJODV64JGzhGz1ynkAhAxBgAVk3QKZMN87lKm5rS0WT7IOVveq3J7MSAkIB45zvNo6tcFnPNbnxudcjBN8jZhj1gd6edmHauatDaJ6Lxx9Ky8ShqwJGq6kPQw1E6WiCY564wEnbYvvNnO3vWYM=';
const IOS_LICENSE =
'FP1.RlBMMQMAAQAZ9Zwi8fHG33dpwB8MAgAAugTVCCTnRx8neRXi7q3IQx09+pM/07ZLOE3uhGCXIfQq/jt8i6+oovCghJsTnzx+LbraSzYnYKhFM+8ZpCt5x6/YNgVNh2Wrdq336ehT9ZmWagxWEm/T4sJw0IlrJwxz+uDS01X95P0og2hQy61Rqh6Q2lCsRpBVj6tVpVU7Q4BcnL43JHUZyFIFzZVhgakFrzZ1v2yMX7hZubx1vsVTDS8XZjOEjNyIs2B7th1XczBQV9jRo/Hzq9IFypKxF+w0kqKeiCGgXtEkpVnhH0q2d3Ol3Hwd7VCvN4rwAfXA4LRpBqMMXgN0iFb4GaZ/5RrcuiWGHt6Se1XRdLaVcYeiafY9i0dGnKpWoYC6Wcc3w7Ud9tt/JH3ZCW0VSX3mhbwizb9aUFpfewQ1233B2QkyydYrmcW9WdRyuIITCZl7lxL4Bu+rMuNvYImrbjnPtUMErhwldzp5/KpVD2n8ZuhQVqo/nvxKVkhu49jA5rncA99rBR/j8PA8tQnrkJA/UzbnGZKe5vaUZHHbc2f/8hoyFAd+bYsgWBBGm98d/JoFNeKA/Lj9qBz/96Vhsb31X/g69Mg2FjeKLmPNLRBsdtB5Gq451Ng7SqVBhSLu3izjcEPw0ZNvfgp41+RXMoxr3HrJ0Nrxe+DjbsVVEhXboNK5UoW0K+YwDpRBssLUBD2v0A5O46pNVDj8BjG6P26LADCBiAJCAUUBMF7fdBJVN4bynNDBBmW66ebB8UiHQWqr3JXWGS4yX+ANEOKFA8x241i0loqcmVGGkNRTdDEuE8T4WaDU9WqBAkIAsgWLPid1PUQVJZVceswxeHuK+NkbA4temoT2sYADekl3tZEA2YA4Ax8Z02A3xY1cT7gAnQz6fMxwoRmYKzZevDQ=';

ID-Document-Recognition-Ionic-Capacitor/example/src/SdkContext.tsx

Lines 60 to 70 in d9f1fea

const act = await setActivation(demoLicense());
console.log('[DocumentReader] setActivation=', act);
if (act !== SDK_SUCCESS) {
const detail = await lastLicenseError();
console.log('[DocumentReader] license error=', detail);
if (!cancelled) {
setStatus(`${statusLabel(act)}${detail ? `: ${detail}` : ''}`);
setReady(false);
}
return;
}

Please contact us to get a license for your own app.

License capabilities (Recognition + Liveness)

After activation, getLicenseStatus reports what the key unlocks. Home shows the same summary on the status bar (for example Ready · Recognition + Liveness). About shows License: ….

Capability Meaning
Recognition OCR, MRZ, barcode/QR, and document type classification
Liveness (authenticity) Document authenticity: physical document, security patterns, photo origin, barcode format

Typical labels:

  • Recognition + Liveness — full identity verification (Result + Security tabs)
  • Recognition — OCR, MRZ, and barcode only; Security stays empty / not checked
  • Liveness — authenticity / document liveness only; OCR/MRZ/barcode stays empty / not checked
  • Not licensed — until you activate

Setup on your own app

You need the document-reader-capacitor plugin, the native runtimes, and a few lines of TypeScript. You do not need the example pages unless you want the demo UI.

1. Install the plugin

npm install git+https://github.com/Faceplugin-ltd/ID-Document-Recognition-Ionic-Capacitor.git
npx cap sync

2. Copy runtimes

  • Android AAR → node_modules/document-reader-capacitor/android/libs/documentreadersdk.aar
  • iOS framework → node_modules/document-reader-capacitor/ios/Frameworks/docsdk.framework

Then npx cap sync again.

3. Activate + recognize

import {
  getMachineCode,
  setActivation,
  init,
  recognize,
  SDK_SUCCESS,
} from 'document-reader-capacitor';

const machine = await getMachineCode(); // FPMC1.…
const act = await setActivation(YOUR_FP1_LICENSE);
if (act !== SDK_SUCCESS) throw new Error('activation failed');
const code = await init();
if (code !== SDK_SUCCESS) throw new Error('init failed');

const json = await recognize(frontUri, backUri ?? null, true);

For live locate, use startLivePreview(false), LocateSession, takeLiveSnapshot, and locateDocument (see example/src/components/DocumentCapture.tsx).

About SDK

Public helpers:

Method Description
getMachineCode() FPMC1.… for license requests
setActivation(license) Activate with FP1.…
getLicenseStatus() Recognition / Liveness flags + label
init() / deinit() Load / unload engine
locateDocument(image) Document locate JSON (corners + score)
recognize(front, back?, authenticity?) OCR / MRZ / barcode → canonical JSON
recognizeResult(...) Typed DocResult
startLivePreview / stopLivePreview / takeLiveSnapshot Native camera under WebView
LocateSession Poll locate for live overlay
lastLicenseError() Last license error detail

Status codes: 0 success, 1 invalid, 2 expired, 3 not activated, 4 init failed, 5 no database, 6 database load error.

Contact

faceplugin.com  faceplugin.com

About

ID document recognition SDK for Ionic Capacitor — scan ID cards, passports, and driver licenses with OCR, MRZ, barcode, and QR recognition. On-device and fully on-premise.

faceplugin.com/id-document-recognition-sdk/

Topics

androidbarcode-scannerdocument-readerdocument-recognitiondriver-license-recognitionekycid-card-recognitionid-document-recognitionid-verificationidentity-verificationionic-capacitorioskycmrzmrz-scannerocron-device-aion-premisepassport-recognitionqr-code

Resources

Readme
MIT license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages