Microblink JS

Javascript SDK for integrating with Microblink API

Demo

Test Microblink UI web component with your passport or US drivers license. Only MRTD and USDL recognizers are enabled in this demo.

To enable more recognizers open component's debugging console (mouse right click on component and select Inspect element, then select Console tab) and set recognizers with Microblink.SDK.SetRecognizers([])

Up to date list of available recognizers are available here: https://api.microblink.com/recognize/info

NOTE: all results are masked and uploaded data is not persisting on the API when Authorization header is not provided. If you want to get unmasked results then you should provide Authorization header (API key and API secret) which you can generate at the Microblink's dashboard.

<script>
  // #1
  //Microblink.SDK.SetEndpoint('https://api.microblink.com');

  // #2
  //Microblink.SDK.SetAuthorization('Bearer ...');

  // #3
  Microblink.SDK.SetRecognizers(['MRTD', 'USDL']);

  // #4
  Microblink.SDK.SetIsDataPersistingEnabled(false);
</script>

#1
This is the default value and it is able to access Microblink API endpoint directly (recommended only for development) but in the production this should be proxied with your backend application.

#2
Please generate your API key and secret here: https://microblink.com/customer/api

#3
You can set array of available recognizers: 'MRTD', 'USDL', 'PDF417', 'CODE128', 'CODE39', 'AZTEC', 'DATA_MATRIX', 'EAN13', 'EAN8', 'ITF', 'QR', 'UPCA', 'UPCE', 'UAE_ID_FRONT', 'UAE_ID_BACK', 'UAE_DL_FRONT', 'VIN', 'SIM', 'CYP_ID_FRONT', 'CYP_ID_BACK', 'CRO_ID_FRONT', 'CRO_ID_BACK', 'KWT_ID_FRONT', 'KWT_ID_BACK', 'ESP_DL_FRONT', 'UK_DL_FRONT', 'MYKAD_FRONT', 'MYTENTERA_FRONT', 'MYPR_FRONT', 'MYKAS_FRONT', 'INDONESIA_ID_FRONT', 'SGP_ID_FRONT', 'SGP_ID_BACK', 'IRL_DL_FRONT', 'HKG_ID_FRONT', 'BLINK_CARD_FRONT'
NOTE: providing more recognizers extends waiting time from the API because OCR engine will execute recognize process on more recognizers, please provide only these recognizers of which kind you are uploading documents.

#4
This demo app is GDPR complained and it does not store any data on the API backend service when Authorization header is not provided.

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.

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 two 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, 3 more sections are rendered to which you can navigate via tab menu: table view of the results, preview of a JSON response from the server and preview of the frame or image from which the results were extracted.

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.

Localization

If you wish to change textual contents inside a 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 than English or you just don't like 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. All you need to do is to provide a 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>.
To clarify, we are providing an example with all currently customizable labels and their default values:

<microblink-ui-web>
    <template class="localization json">
        {
            "buttons": {
                "browse": "Browse",
                "cameraLocal": "Use web camera",
                "cameraRemote": "Use remote phone camera",
                "tryAgain": "TRY AGAIN",
                "takePhoto": "TAKE A PHOTO",
                "copy": "Copy to clipboard"
            },
            "labels": {
                "dragDrop": "Drag and Drop\ndocument here OR",
                 "nativeCamera": "Choose image from \ndevice or camera app:",
                "cameraActivate": "Activate your camera to capture the ID document:",
                "errorMsg": "We're sorry, but something went wrong. Please try again.",
                 "permissionMsg": "Enable camera please",
                "holdStill": "HOLD STILL",
                "table": {
                    "keys": "Data field from the ID",
                    "values": "Value"
                },
                "uploading" : "Uploading",
                "processing" : "Processing",
                "analyzing" : "Analyzing",
                "extracting" : "Extracting data",
                "almostDone" : "Almost done",
                "openLinkAtSmartphone": "Please open exchange link in the browser at smartphone.",
                "generatingExchangeLink": "Generating exchange link...",
                "exchangeLinkTitle": "Exchange link is"
            },
            "tabs": {
                "retake": "RETAKE",
                "results": "RESULTS",
                "image": "IMAGE",
                "json": "JSON"
            }
        }
    </template>
</microblink-ui-web>

You can use this example as a template and just change JSON values for your purposes.
There is a work in progress to provide a better support for single page apps and a better input format.

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:

Property	Description
--mb-hem	This is basically CSS rem unit for the component. Default value is set to page's 1rem. If you wish to scale up or down text size of the component, use this property.
--mb-widget-font-family	Use to define component's font family. Default value: Helvetica, Tahoma, Verdana, Arial, sans-serif
--mb-widget-border-width	Border width of the entire component. Default value: 0
--mb-widget-border-color	Border color of the component. Default value: black
--mb-widget-background-color	Background color of the component. Default value: transparent
--mb-alt-font-color	This property is used to set font color of the initial display labels. Default value: black
--mb-btn-font-color	Use to set buttons' font color. Default: white
--mb-btn-background-color	Background color of buttons. Default: black
--mb-btn-background-color-hover	Background color of hovered buttons. Default: dimgrey
--mb-btn-flip-image-color	Color of the camera flip button. Default: black
--mb-btn-cancel-color	Color of the cancel button (camera exit button). Default: black
--mb-card-layout-border-color	Border color of the card overlay. Default: black
--mb-btn-border-radius	Set the buttons' border radius. Default values is 5px
--mb-dropzone-hover-color	Background color of drag and drop area when hovered with some dragged document. Default value: rgba(0, 0, 0, .25)
--mb-loader-font-color	Font color of the loader dialog during file upload and processing. If not set, fallback to --mb-dialog-font-color.
--mb-loader-background-color	Background color of the loader dialog. If not set, fallback to --mb-dialog-background-color.
--mb-dialog-font-color	Use to set font color of the permission and error dialogs. Default value: black
--mb-dialog-background-color	Use to set background color of the permission and error dialogs. Default value: white
--mb-counter-font-color	Use to set font color of the counter display, shown when capturing frames. Default value: white
--mb-counter-background-color	Use to set background color of the counter display. Default value: rgba(0, 0, 0, 0.7)

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

Property	Description
--mb-tabs-font-color	Font color of tabs. Default value: white
--mb-tabs-background-color	Background color of tabs. Default value: black
--mb-tabs-border-width	Use to set bottom border width for underlined text inside tabs. Default value: 4px
--mb-tabs-active-color	Use to set font color of active tab, the one whose corresponding container is displayed. Default value: first fallback to --mb-tabs-hover-color, second to #ddd
--mb-tabs-hover-color	Use to set font color of hovered tab. Default value: first fallback to --mb-tabs-active-color, second to #ddd
--mb-default-font-color	Use to set the font color of table results display. Default value: black
--mb-table-header-background-color	Use to set the background color of table headers in a results display. Default value: #f2f2f2
--mb-json-color-key	Inside JSON view, use to set font color of the keys. Default value: #ff0000
--mb-json-color-string	Inside JSON view, use to set font color of string values. Default value: #008000
--mb-json-color-number	Inside JSON view, use to set font color of number values. Default value: #ffc000
--mb-json-color-boolean	Inside JSON view, use to set font color of boolean values. Default value: #0000FF
--mb-json-color-null	Inside JSON view, use to set font color of the null values. Default value: #ff00ff

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.

How it works

1. component is loaded at the browser on desktop
2. user requests feature by click to the button Use remote phone 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.

Development

Realtime build

npm start