Skip to content

Latest commit

 

History

History
181 lines (132 loc) · 6.76 KB

README.md

File metadata and controls

181 lines (132 loc) · 6.76 KB

Client library

Client library is a small JS library which simplifies communication with BlinkID Cloud API and BlinkID Self-hosted API backend services.

Even though client library is built with BlinkID ImageCapture In-browser SDK in mind, it can be used separately.

For more information about endpoints, request and response formats of Cloud API and Self-hosted API see official documentation:

Table of contents

Installation

Client library is bundled within BlinkID ImageCapture In-browser SDK, but is separated from the rest of the codebase so it can be include on its own.

NPM

# Install NPM package
npm install --save-dev @microblink/blinkid-imagecapture-in-browser-sdk
// Include Client from JS/TS files
import { Client } from "@microblink/blinkid-imagecapture-in-browser-sdk";

Standalone (UMD) bundle

Since the client library is published on NPM, it's possible to download the library via public CDN services.

However, we strongly advise that you host the JavaScript bundle on your infrastructure since there is no guarantee that the public CDN service has satisfactory uptime and availability throughout the world.

<!-- After successful load, global variable `Client` is available. -->
<!-- IMPORTANT: change "X.Y.Z" to the version number you wish to use! -->
<script src="https://cdn.jsdelivr.net/npm/@microblink/[email protected]/client-library/dist/client-library.min.js"></script>

Keep in mind that the jsDelivr CDN is used for demonstration, it's not intended to be used in production!

ES module

The library is also packaged as a classic ES module which can be downloaded via public CDN services.

However, we strongly advise that you host the JavaScript bundle on your infrastructure since there is no guarantee that the public CDN service has satisfactory uptime and availability throughout the world.

/* IMPORTANT: change "X.Y.Z" to the version number you wish to use! */
import { Client } from "https://cdn.jsdelivr.net/npm/@microblink/[email protected]/client-library/es/client-library.mjs";

Keep in mind that the jsDelivr CDN is used for demonstration, it's not intended to be used in production!

Usage

import
{ 
    Client,
    Configuration,
    ApiType,
    ResponseHealthcheck,
    ResponseRecognition
} from "@microblink/blinkid-imagecapture-in-browser-sdk/client-library";

/* Create instance of Client */
const configuration: Configuration =
{
    /* [OPTIONAL] Add authorization header to every request */
    headers:
    {
        "Authorization": "Bearer ..."
    }
}

/* Use 'ApiType.SelfHosted' for Self-hosted solution */
const client = new Client( ApiType.Cloud, configuration );

/* Check API availability */
client.getHealthcheck()
    .then( ( response: ResponseHealthcheck ) => { /* API is available */ } )
    .catch( ( error: ResponseHealthcheck ) => { /* Could not access API */ } );

/* Extract data from image */
const image = "..."; // Base64 representation of image

/* See API documentation for full list of endpoints and body parameters */
client.recognize( "/v2/recognizers/blinkid-single-side", { "imageSource": image } )
    .then( ( results: ResponseRecognition ) =>
    {
        const recognitionResults = results.response.data.result;

        /* Handle case when results are empty */
        if ( recognitionResults.recognitionStatus === "EMPTY" )
        {
            /* Inform the user */
        }

        /* Do something with results */
    } )
    .error( ( error: ResponseRecognition ) =>
    {
        /* User friendly message */
        const message = error.error.message;

        /* Do something... */
    } );

For complete JavaScript examples for both Cloud API and Self-hosted API see HTML files in the examples directory.

Customization

All configuration options can be seen in data-structures.ts file.

Custom endpoint

Since it's a good practice to place an API behind a proxy, configuration supports apiLocation property which can be used to define the exact location of an API service.

import { Configuration } from "@microblink/blinkid-imagecapture-in-browser-sdk/client-library";

const configuration: Configuration =
{
    apiLocation: "http://example.com"
}

Custom headers

The client library implements mechanism which includes response headers from every API call. Furthermore, it's possible to add custom headers which are included in every request towards the API.

import { Configuration } from "@microblink/blinkid-imagecapture-in-browser-sdk/client-library";

const configuration: Configuration =
{
    // Add all custom headers, where every value is a string
    headers:
    {
        "Authorization": "Bearer ...",
        ...
    }
}

Custom user-friendly messages

By default, Cloud and Self-hosted API services will return various error messages in different scenarios. Even though it's a good practice to handle those messages in the proxy application between the frontend client and API, this library provides a mechanism to change default messages.

Furthermore, this mechanism could be useful if this library is used in application with multiple interface languages. During the initialization of Client class, messages can be set in accordance with the user interface language.

List of general error messages can be found in data-strucutres.ts file.

List of API specific messages can be found in service.cloud.ts and service.self-hosted.ts files.

import { Configuration } from "@microblink/blinkid-imagecapture-in-browser-sdk/client-library";

const configuration: Configuration =
{
    messages:
    {
        // Overwrite default "GENERIC_ERROR" message
        "GENERIC_ERROR": "Oops, there was an error during processing..."
    }
}