Integration Guideline [JavaScript]
This page contains instructions on how to integrate LIQA into your web service
Last updated
This page contains instructions on how to integrate LIQA into your web service
Last updated
LIQA represents a complex combination of multiple AI algorithms. Some of them require model weights to be fetched from the server. Also, some time is necessary for model compilation on the device. Finally, LIQA requires some DOM elements and settings to be provided to initialize the visualization correctly before the camera starts.
To manipulate all these actions, LIQA has a pipeline of simple methods:
These methods require the LIQA instance class to be already present on the page. See the API Documentation for all described methods for the API.
Next, we will use a general term of a web application with at least 1 page called Image Collecting Page - this is a webpage with LIQA loaded, initialized, and called for live video capturing and processing.
The load
method with compileModels: true
(see API Documentation) requires some time (see Few words about compiling models). This time can be "hidden" from an end-user experience in the case of a Single Page Application (SPA).
If your web application model is a single-page application (SPA) with several "user" pages before the image collecting page (e.g. welcome page, survey before image collection, etc.), the call of the load
method with compileModels: true
can be separated from the init
and play
methods. This will decrease the loading time on the image collecting page before the video appears.
In case if your web application model is a SPA with only one page or a common website with independent pages, the load
method can not be separated from init
and play
. In this case the best practise would be to call the load
method with compileModels: false
followed by calling the init
and play
methods on the same page.
LIQA is distributed as a private NPM package with simple installation. Please follow the Try LIQA: access request instructions to contact us to get access to the registry. Leave us a message with a short description of your company, planned usage (test of technology embedding, small / medium / large business, etc.), and a contact e-mail so we could get back to you
After approving the request, you will be contacted via e-mail by Haut.AI and receive credentials for accessing the registry. For authorization, you will get your personal token as a long string:
password
- BASE64_ENCODED_PERSONAL_ACCESS_TOKEN
.npmrc
file
registry_link
- URL to set connection to the repository (smth like https://pkgs.dev.azure.com/haut-ai/.../npm/registry/)
Please, pay attention that the credentials always have an expiration date.
Please, store the provided credentials securely on your side
Go to your system Home directory:
for Windows (by default, installed on C drive): C:\Users\%username%
for Linux and MacOS: $HOME/
Put the provided .npmrc
file in your Home directory
If you already have .npmrc
file, open it and append the lines from the shared by Haut.AI
Put your password
instead of "<BASE64_ENCODED_PERSONAL_ACCESS_TOKEN>" placeholder
Put your contact e-mail instead of <your contact email>
Call these commands in your project with the provided to you registry_link
Update LIQA to fetch the latest bug fixes:
Make sure to update scripts:
cp -r ./node_modules/@liqa/e-commerce/scripts ./path/to/public/assets
Copy external scripts that will be fetched in LIQA:
if you use LIQA as an npm
package
if you use LIQA as an independent local library
Import LIQA inside of your code:
Initialize LIQA instance:
Load LIQA (fetch and optionally compile models):
The duration of theload
method depends on the Internet connection speed. For example, it requires only 0.3s at 30Mbps if compileModels
is set to false.
You may turn off a model compilation during the load
method, and in this case, the compilation will happen during the first frame of a video stream.
The model compilation is computationally intensive. It requires different times depending on hardware: from ~1s on modern devices to more than 10s on desktop or old devices.
Cache header allows your webpage to cache static files on user device. For LIQA, this allows to store neural networks model weights after being once downloaded.
Add <meta />
tag to your index.html
:
The max-age=<N>
response directive indicates that the response remains fresh until N seconds after the response is generated.
We do not recommend making this value > 2 days to keep your system always up to date (2 days = 151200 seconds)
Provide a container and settings (see more at API Documentation):
Provide an empty div
container. LIQA will create the necessary elements by itself:
Manually create a canvas and video elements inside of div
container and pass it as a parameter. LIQA will use the provided elements instead of creating a new one:
Please, note, that the manual initialization is not a default way of LIQA usage and you are responsible for the correctness of the provided elements. At the same time, the manual initialization with a custom div
container creation may help in case of integration to third-party services and elements ownership issues.
Start stream:
Setup a subscription to RxJS Observable to receive LIQA results per frame.
What to do with LIQA results?
LIQA can help your end-user to understand the image quality problem and fix it. LIQA returns simple and clear statuses of parameters, influencing image quality. Please, visit the qualityStatus page to learn more about the values that are returned.
Humans mostly perceive the information visually. We suggest your service transform LIQA results to visual user feedback by demonstrating warnings, status bars, and hints with only you to decide how this may look like.
To help you choose the best way to deliver the feedback to your end-user, we prepared several examples of LIQA results parsing with different levels of detail. You are welcome to start building your perfect feedback loop by investigating our examples:
Level 1: "All or nothing"
Level 2: "State the reason"
Level 3: "Comprehensive feedback"
The main goal of LIQA usage is to help collect a good quality high-resolution image of an end-user face. LIQA returns results of image collection action as RxJS Observables. To get the results it is necessary to set up subscriptions before image collection actions may happen.
Set up a subscription to selfieImage
RxJS Observable to receive a final high-resolution selfie image:
We highly recommend to show the resulting image to your end-user right after the selfie image collected. It might be also very helpful to allow the user to retake the image in case of failure.
Please, visit our example here: Selfie capturing results parsing
From the 5.0
version, LIQA allows to predict landmarks (facial key points) on the resulting selfie image. Please, refer to Observables: Data Collection to see the map of landmarks.
Set up a subscription to selfieLandmarks
RxJS Observable to receive an array of facial key points (landmarks) with (X, Y, depth) coordinates:
Landmarks prediction is an optional behavior of LIQA. To activate it, set predictLandmarks
parameter in config.json
to true
. If it is not activated, the selfieLandmarks
observable would contain None
The predicted landmarks provide your system with a possibility for user engagement. The exact usage of the landmarks is limited mostly by your system design.
Please, visit our example here: Selfie capturing results parsing
From the 5.0
version, LIQA allows both manual and automatic image capturing when all the image quality requirements are satisfied. Simply speaking, when the image quality of the live stream is good enough, the system (auto) or the end-user (manual) can trigger a captureSelfie
action. To allow a manual call, set up some UI with this call:
Autocapturing is an optional behavior of LIQA. To activate it, set autoSelfieCapture
parameter in config.json
to true
. If it is not activated, the system would expect the manual selfie capturing control (by actions from an end-user)
The call of captureSelfie
method before the play
method is completed will return an error.
When you are ready to finish LIQA work on the current page it is better to remove the container (provided in the init
method) from the page by calling the unmount
method:
Finally, call the exit
method to quit all work with LIQA.
On this page several free for commercial use materials were utilized for illustration purposes:
*
an icon made by Icongeek26 from https://www.flaticon.com/
**
an icon made by wanicon from https://www.flaticon.com/
Update LIQA to download the latest major version ( may influence API). Here x
is the latest major version.