@microblink/capture
v1.2.3
Published
A smart image capturing library for WebAssembly-enabled browsers
Downloads
293
Keywords
Readme
Capture SDK for browsers
The Capture Browser SDK gives you the ability to auto-capture high-quality images of identity documents in a user-friendly way. The SDK provides you with a rectified image of the document, ensuring a high success rate in extracting document text or verifying the document's validity.
Users are guided to avoid glare, blurred images, bad lighting conditions, fingers covering the document, or too much tilt. The SDK is able to recognize if a document is single-sided (i.e., passport) or double-sided (i.e., driving license) and prompt the user to scan the back side of the document when needed.
In the results, you can obtain a cropped, perspective-corrected image of the document, along with the original frame. These can be processed by your webapp in any way required. The SDK is lightweight and can be easily integrated into your webapp, blending seamlessly with your design.
Installation
The Capture SDK is available as a package on NPM for use with a module bundler.
# npm
npm install @microblink/capture
# yarn
yarn add @microblink/capture
# pnpm
pnpm add @microblink/capture
Obtaining a licence
A valid license key is required to initialize scanning. You can request a free trial license key after registering on Microblink Developer Hub. The license is bound to the domain of your app.
Hosting environment
In order for the SDK to work it needs to run inside a secure context. Additionally, to run the threaded version of the SDK, the following headers need to be set on your server:
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
Otherwise, you will only be able to run the single-threaded version of the SDK.
In order to load the accompanying Wasm files and Web Workers, you also need to host them locally on your dev server. These files can be found inside the node_modules/@microblink/capture/dist/resources
directory after installation. The /resources
directory must be hosted without modification of the directory name or its contents.
The dev environments for the example apps have these set and you can use them as a reference.
Examples Quick Start
Requirements
In order to run the examples provided in the GitHub repository, you'll need the following tools:
NodeJS LTS (18.x)
- Prefer using
nvm
on dev machines:
nvm install --lts nvm use --lts
- Prefer using
pnpm
- alternative package manager to
npm
- easiest to install using
npm install -g pnpm
- alternative installation methods
- alternative package manager to
Device requirements
Additionally, your device will need a camera capable of providing a video stream with a minimum resolution of 1920x1080.
The minimum supported browser versions are Chrome 96, Firefox 79 and Safari 15.2. Web views are not supported as they are not providing a secure context.
Running the provided examples
The examples provided in the GitHub repository can be run by first building the SDK by running pnpm build
, and then navigating to the examples found in /apps/*
and running pnpm dev
for the dev server or pnpm serve
for the production build.
These examples will move the node_modules/@microblink/capture/dist/resources
as part of the build step to Vite's public folder, generate a local HTTPS certificate and apply the appropriate headers to Vite's dev server.
Using the SDK
It is strongly recommended to use TypeScript and an IDE that has a TypeScript language server during development as the SDK is strongly typed and provides JSdoc comments, links, usage examples, autocomplete, and other Intellisense features.
Using the provided UI component with createCaptureUi
The simplest way to initialize the SDK and start capturing is to call createCaptureUi
and provide it with a licence key. This will mount a full-screen capturing UI in your web app. Make sure to also load the CSS styles for the component.
import { createCaptureUi } from "@microblink/capture";
import "@microblink/capture/style.css";
createCaptureUi({
sdkSettings: {
licenseKey: "YOUR_LICENCE",
callbacks: {
onCaptureResult: (result) => {
/* do something with the result */
},
},
},
});
Headless usage with createCaptureSdk
You can also use the Capture SDK without the provided UI and build your own experience by using createCaptureSdk
. All the mechanisms that the Capture UI uses are provided by the object returned by this method.
import { createCaptureSdk } from "@microblink/capture";
const sdk = await createCaptureSdk({
licenseKey: "YOUR_LICENCE",
callbacks: {
onCaptureResult: (result) => {
/* do something with the result */
},
},
});
await sdk.startCameraStream(document.getElementById("videoElementId"));
The SDK will terminate automatically if the video element is dismounted and requires no handling on the developer's end.
Configuration
Configuring the Capture SDK
The SDK can be configured on initialization using createCaptureSdk(settings)
. The configuration documentation can be found on CaptureSdkSettings
.
The capturing process is handled using the Analyzer
. The configuration settings for the Analyzer
can be found on AnalyzerSettings
.
Configuring the Capture UI
createCaptureUi
takes a CreateCaptureUiSettings
configuration object as a parameter with both CaptureSdkSettings
that configures the SDK behaviour, and UiSettings
which configures the UI itself.
You can configure the mount point of the UI, toggle the display of the onboarding screen and help screens, the error screen and provide your own localization strings.
You can find a list of all the localization strings in packages/capture-main/src/ui/locales/en.ts
Advanced usage
Instantiating the Capture UI with a preloaded CaptureSdk
instance
In cases you want to reuse the CaptureSdk
instance between component mounts/dismounts, preload it before showing the UI, or otherwise have greater control over the lifecycle of the SDK, you can use createCaptureUiWithInstance
, which instead of SDK settings takes an instance of the CaptureSdk
. You can see the usage in the example-solidjs-sdk-preinit
.
State management and subscriptions
The Capture SDK tracks its internal state on the ReactiveStore
object, which is implemented using Zustand.
The user can get the internal state of the SDK at any time by calling getState()
on the CaptureSdk
object returned by createCaptureSdk
. CaptureSdk
is also available on the CaptureComponent
instance returned by createCaptureUi
.
You can also subscribe to state changes by calling CaptureSdk.subscribe()
. Detailed documentation for using this feature is available here.
UI customization
The UI can be customized by either overriding the CSS variables found at packages/capture-main/src/ui/root-styles.scss
, or by manually targetting the CSS classes applied to the UI component.
All components rendered by the UI are nested under .mb-style-scope
which provides some base styles.
Detailed capturing process information
You can find details on the internal state of the capture process using the onFrameAnalysis
callback. This callback will provide you with an ImageData
instance of the previously processed frame and the FrameAnalysisResult
.
Low-level access Direct API
This mode gives users the capability to directly interact with the Analyzer
instance, bypassing the provided functionality in the Capture SDK such as camera and video management, user feedback, callbacks and state management.
import { createDirectApi } from "@microblink/capture";
const directApi = await createDirectApi({
licenseKey: "YOUR_LICENCE",
});
// The user is free to use methods available on
// the `directApi` to fit their use case
Troubleshooting
Integration problems
If you are experiencing issues with the SDK integration, first make sure that you have followed the integration instructions and used our provided examples as reference. Also make sure that your device meets the requirements. If you're still having problems, please contact us at help.microblink.com.
Licencing problems
If you are getting "invalid licence key" error or having other licence-related problems, first check the console. All licence-related problems are logged to error log so it is easy to determine what went wrong.
When you have determined what is the licence-related problem or you simply do not understand the log, you should contact us help.microblink.com. When contacting us, please make sure you provide following information:
Contact
For any other questions, feel free to contact us at help.microblink.com.