Microblink JS

Microblink is deprecating this frontend solution to make way for a more efficient image acquisition component — BlinkID ImageCapture In-browser SDK. You can still use this library but we will not provide technical support for it in case you encounter any issues and we won't be making any changes to it moving forward.

Javascript SDK for integrating with Microblink API

Demo

Demo app. implementation is available on Codepen.

More details about product with demo page are available here.

About

This package includes library for image preparation and HTTP integration with Microblink API publicly hosted on https://api.microblink.com or for self hostend on-premise solution with Microblink API wrapped in Docker image, which is available on Docker Hub.

Also, this package has an Microblink API UI web component available as custom HTML tag <microblink-ui-web></microblink-ui-web> which has native camera management for mobile and desktop devices with WebRTC support and file management solution.

Browser compatibility

Latest ✔	Latest ✔	Latest ✔	Latest ✔

How to use

Install package

npm install microblink

Using CDN

You can also link the scripts from unpkg: https://unpkg.com/microblink/dist/

If you wish to use only SDK without UI component, use minified version microblink.sdk.min.js

For the whole thing, we recommend using es6 version for better performance. If you really want es5, you can find minified version here.

Microblink API Proxy

To avoid the leaking of your credentials (Microblink API Authorization header = API key + API secret) by your visitors in the frontend Javascript application, your frontend application in the production environment should has an access to the backend proxy application and backend proxy application should append the authorization credentials, and also in this proxy application you could execute your additional business logic.

Example implementation in Node.js Express application

Minimum proxy implementation which ensure the security for your credentials are available here https://github.com/microblink/microblink-api-proxy-example this example can be easily hosted at Webtask.io service in few minutes. More details about this example are available in this README.md

Using web component

To skip developing your own front-end UI solution, we have included our web component in the package to provide you quick and easy integration, theme customization and labels translation. Under the hood we are using WebComponents technology, custom elements and shadow DOM. Just insert our custom html element <microblink-ui-web></microblink-ui-web> into your page and the component will be rendered with initial setup.

Javascript events

As we have developed our UI solution as a custom html element, we have also implemented it to dispatch additional HTML DOM events which can easily be accessed with javascript.
Component fires two kind of events which are important for interacting with the rest of the page. Adding event listeners is the way to communicate with the component.

resultReady
This event is fired after successful image upload or scan and the results are available on the client side. By listening to this event you are able for example to fill out your web form with the extracted data.
Plain javascript code example:

document.querySelector('microblink-ui-web').addEventListener('resultReady', function(/*CustomEvent*/ event) {
  var result = event.detail.result;
  /* do something with the result */
});

error
This event is fired in case of any kind of error during component use. More information can be extracted from ErrorEvent argument such as error message. By listening to this event you can for example notify user of a failed scan, upload, connection error and so on.
Plain javascript code example:

document.querySelector('microblink-ui-web').addEventListener('error', function(/*ErrorEvent*/ event) {
  var error = event.error, message = event.message;
  /* do something with the error */
});

Setting component dimensions

The component will initially stretch to the size of it's container. To control component's width and height, we recommend wrapping it inside a single <div> and setting css dimension properties on wrapper <div> element.
For better UX, when viewing your page from a mobile browser, the component's height is set to 100% height of the viewport, but not more than a container's height. This gives you an option to control component's height inside viewport height range.

Attributes

Currently the component supports four additional boolean attributes. These can be set like any other HTML attributes.

tabs - this is for enabling results display inside component area after document scan or document file upload. Beside initial screen with action buttons, 2 more sections are rendered to which you can navigate via tab menu: table view of the results and preview of a JSON response from the server.

autoscroll - this is a feature for mobile devices intended to improve UX. When scrolling through your page with this option enabled, the vertical positioning of the page will be set to the start of the component when distance of the component's top edge is near to the top edge of the viewport. This could help mobile users to have the whole component placed inside a viewport.

webcam - this is for enabling or disabling the option to use web camera. To disable the use of webcam set the webcam attribute to "off".

upload - this is for enabling or disabling the option to use upload image. To disable the use of upload image set the upload attribute to "off".

fullscreen - this is for enabling or disabling the option to open web camera video stream fullscreen. To disable the use of fullscreen camera video stream set the fullscreen attribute to "off".

Localization

If you wish to change textual contents inside component, we are offering you an easy way to do this without the need for you to do cumbersome additional javascript manipulation. Maybe you want your page in a different language or you just don't want our default English labels.
As for the implementation details of this feature, we are using <slot> elements as placeholders in a shadow DOM structure. The slots will be generated automatically.

<microblink-ui-web> has a method setLocalization which can receive JSON string or javascript object as parameter, containing translated or adjusted text for component's labels. This is the recommended way. Calling this method will reset current localization texts and place new ones. To clarify, we are providing an example with all currently customizable labels and their default values:

document.querySelector('microblink-ui-web').setLocalization({
  "buttons" : {
    "browseDesktop": "Upload image",
    "browseMobile": "Take or upload photo",
    "cameraRemote": "Use mobile camera",
    "cameraLocalDesktop": "Use web camera",
    "cameraLocalMobile": "Use camera",
    "dropFiles": "Drop files to upload",
    "tryAgain": "TRY AGAIN",
    "takePhoto": "Take a photo",
    "copy": "Copy to clipboard",
    "confirm": "USE PHOTO",
    "retake": "RETAKE"
  },
  "labels" : {
    "chooseInputMethod": "Choose input method",
    "generatingExchangeLink": "Generating exchange link...",
    "exchangeLinkTitle": "Exchange link is",
    "openLinkAtSmartphone": "Please open exchange link at the smartphone with OR reader",
    "remoteCameraIsPending": "Remote camera is pending...",
    "remoteCameraIsOpen": "Remote camera is open...",
    "imageIsUploading": "Image is uploading...",
    "imageIsProcessing": "Image is processing...",
    "videoTagUnsupported": "Your browser does not support video tag",
    "uploading" : "Uploading",
    "processing" : "Processing",
    "analyzing" : "Analyzing",
    "extracting" : "Extracting data",
    "almostDone" : "Almost done",
    "errorMsg": "We're sorry, but something went wrong. Please try again.",
    "permissionMsg": "Enable camera please",
    "notFoundErrorMsg": "No camera was found on your device",
    "notAllowedErrorMsg": "You have denied camera access permission",
    "scanningFinishedNoDataTitle": "Document not recognized",
    "scanningFinishedNoDataMessage": "Please try again with a supported document or select a different recognizer",
    "unsupportedFileType": "Unsupported file type",
    "selectRecognizers": "Please select one or more recognizers to start scanning",
    "noRecognizersSelected": "No recognizers selected",
    "webRtcUnsupported": "WebRTC not supported by your browser"
  },
  "tabs" : {
    "back": "Back",
    "results": "Results",
    "json": "JSON"
  }
});

To retain compatibility, we are supporting old, now discouraged way of interpolating json directly into html:

You can provide JSON content via <template class="localization"> element and place the template as a child of <microblink-ui-web>. The template text content should be an URL to external JSON file, or you can insert JSON directly as a template content in which case you should append "json" class to <template>.
Here is an example with all currently customizable labels:

<microblink-ui-web>
	<template class="localization json">
		{
			"buttons" : {
				"browseDesktop": "Upload image",
        "browseMobile": "Take or upload photo",
				"cameraRemote": "Use mobile camera",
				"cameraLocalDesktop": "Use web camera",
				"cameraLocalMobile": "Use camera",
				"dropFiles": "Drop files to upload",
				"tryAgain": "TRY AGAIN",
				"takePhoto": "Take a photo",
				"copy": "Copy to clipboard",
				"confirm": "USE PHOTO",
				"retake": "RETAKE"
			},
			"labels" : {
				"chooseInputMethod": "Choose input method",
				"generatingExchangeLink": "Generating exchange link...",
				"exchangeLinkTitle": "Exchange link is",
				"openLinkAtSmartphone": "Please open exchange link at the smartphone with OR reader",
				"remoteCameraIsPending": "Remote camera is pending...",
				"remoteCameraIsOpen": "Remote camera is open...",
				"imageIsUploading": "Image is uploading...",
				"imageIsProcessing": "Image is processing...",
				"videoTagUnsupported": "Your browser does not support video tag",
				"uploading" : "Uploading",
				"processing" : "Processing",
				"analyzing" : "Analyzing",
				"extracting" : "Extracting data",
				"almostDone" : "Almost done",
				"errorMsg": "We're sorry, but something went wrong. Please try again.",
				"permissionMsg": "Enable camera please",
				"notFoundErrorMsg": "No camera was found on your device",
				"notAllowedErrorMsg": "You have denied camera access permission",
				"scanningFinishedNoDataTitle": "Document not recognized",
				"scanningFinishedNoDataMessage": "Please try again with a supported document or select a different recognizer",
				"unsupportedFileType": "Unsupported file type",
				"selectRecognizers": "Please select one or more recognizers to start scanning",
				"noRecognizersSelected": "No recognizers selected",
				"webRtcUnsupported": "WebRTC not supported by your browser"
			},
			"tabs" : {
				"back": "Back",
				"results": "Results",
				"json": "JSON"
			}
		}
	</template>
</microblink-ui-web>

You can use this example as a template and just change JSON values for your purposes.

Theme customization

To avoid leaking css styles inside of a component or outside of it, we are using a shadow DOM for scoping purposes. This way the component's css is isolated from the rest of the page and there are no unintentional overrides. However, you probably wish to adjust component style so it can better fit with the rest of your page design. With this in mind, we provide style hooks in the form of CSS custom properties, also knows as CSS variables. CSS custom properties' values set on the component element have higher priority than those defaults set inside of the shadow DOM (:host selector) and for this reason they are able to pierce the barrier of the shadow DOM from the outside.
We have defined dozens of custom properties so you have plenty of options when creating your own theme for the component. For more advanced styling options, such as creating your own layout, inserting icons at certain places, more labels and so on, you will have to directly manipulate HTML and CSS inside of the component's shadow DOM structure. Below is the list of all currently available style hooks with their explanations:

There are additional properties to style component if you are using 'tabs' option to display results inside a component.
They are listed below:

Feature: desktop-to-mobile

With this feature component is able to starts at the browser on the desktop computer and use remote camera on the smartphone to capture document, call API and returns results to the desktop where component was initially started.

All data by default is exchanged over Firebase project through Firestore collection, this can be replaced by modifying the component and Microblink SDK internaly.

Source

Microblink Scan Web is a standalone Angular application available as GIT submodule at scan directory.

How it works

1. component is loaded at the browser on desktop
2. user requests feature by click to the button Use mobile camera
3. component at the desktop generate exchange link with QR code and secret key for AES encryption
4. user at smartphone should open generated exchange link (link contains scan identificator and AES secret key for encryption), recommended way is to scan QR code with QR reader integrated in native camera app on the iOS and Android or with custom QR reader
5. at mobile user takes document with native camera
6. component loaded at smartphone calls Microblink API, encrypt result and store it to the exchanged object at Firebase.Firestore
7. component loaded at desktop is subscribed for the changes, reads encrypted results stored in Firebase.Firestore, decrypts it and display it to the user

Firebase project setup

Look at the sample/index.html and replace Firebase app configuration with your project's credentials. To exchange data through database which you are the owner.

SDK Setup

SDK methods will allow you to manipulate with request according to your needs.

Use this method if you are using country specific recognizers. Multiple recognizers are allowed here.

Microblink.SDK.SetRecognizers(['MRTD']);

This method allows you to set the endpoint of the API service. If you are using Self-hosted API, set this to the address where your service is available. If you wish to test just the API functionality you can do that by using our demo service, which is available at https://demoapi.microblink.com.

Microblink.SDK.SetEndpoint('http://localhost:8081');

This methods allows you to use our improved recognizers, or to test how our Cloud API works. Set request parameters for desired recognizer. This method will override Microblink.SDK.SetRecognizers() method. This way, you can use only one recognizer per request. Available recognizers are (BLINK_ID, ID_BARCODE, MRTD, PASSPORT, VISA and MRZ_ID).

Microblink.SDK.SetupRecognizerRequest('MRTD');

Disable persisting uploaded data (this option is ignored if Authorization header is set).

Microblink.SDK.SetIsDataPersistingEnabled(false);

Setup export images.

Microblink.SDK.SetExportImages(true);

Set Authorization header (Bearer + ' ' + apiKey + apiSecret) - generate one in Microblink dashboard at https://microblink.com/customer/api. If endpoint is not equal to the default value https://api.microblink.com then Authorization header is ignored (self-hosted Microblink API by default has disabled authorization with Microblink API key/secret).

Microblink.SDK.SetAuthorization('Bearer OTgzMGE95GU0YTA1NGQ1OTk5OTVhZjk3OTJiNjM0YzE6NWMyMzhiNzktYmE5My00MTMzLWFiNTHUMWRhYTk4NWI5Mzcz');

Set up UserID if needed.

Microblink.SDK.SetUserId('test-user-id@microblink.com');

Default listeners (API's callbacks) are defined inside of the microblink-js UI component, but it is possible to configure global listeners to implement custom success/error handlers.

Microblink.SDK.RegisterListener({
  onScanSuccess: (data) => {
    console.log('Data from Microblink API is', data);
  },
  onScanError: (error) => {
    console.error('Error from Microblink API is', error);

    // Display generic alert
    if (error.summary) {
      alert(error.summary);
    }
  }
});

Development

npm install

Realtime watch & build

npm start

Build release

npm build and fetch files from dist directory