Introduction
Common parameters
Option 1: Direct link to the MachineSense Client
Option 2: Link to partner's page where WASM is integrated in an IFrame
Option 3: Full integration of KYC API into partner's page
KYC ID-doc SCAN is a MachineSense service that allows to scan ID-documents (passports, ID-cards, driving licenses) and extract data from them. This service is available as a web application (including in-mobile-browsers) via MachineSense client-side component, compiled as WebAssembly module. This page describes how to integrate this component into your web application.
Note: This page describes only client-side integration. For server-side integration see
KYC ID-doc SCAN: Server-side integration.
For high-level description of the process, see KYC ID-doc SCAN: Guide.
WebAssembly (WASM) is a binary instruction format for a stack-based virtual machine. MachineSens WASM components are written in C++ and are loaded into the browser as a binary file. The component is loaded asynchronously and is executed in a separate thread. The component is loaded from the MachineSense server, so the component is always up-to-date.
WASM component is visible to our partner-developers as a JavaScript object, which has a set of methods.
Method-calls are varying, depending on the mode in which the integration is done.
Partner developers have three different options when integrating Machine Sense KYC. Each of the options provides a different level of flexibility and complexity:
In each of the integrations client side needs several parameters. Some of these parameters are constants
and some are session based and require partner backend to communicate with Machine Sense Backend API.
Those common parameters are:
"i".
"l". (example values l=nl, l=en, etc.)
nld-id, nld-pass, etc.
"s".
This option is the simplest integration option. If allows MachineSense partner to generate a link which is then displayed or sent to the end user.
Note:
Since (cam) scanning works the best if used on a mobile phone (mobile phone cameras are typically of much better quality
and resolution than desktop webcams), it makes sense to present a QR-code with the link or send the link to the end-user
via SMS or email to follow-up on the mobile phone.
After successfully performing the KYC procedure, partner will typically direct the end-user to the
desktop version, if that's how the process started.
If the process is performed entirely on the mobile device (no desktop), then the end-user should simply continue.
The partner's backend calls Machine Sense Backend API to get Session ID. After acquiring this parameter, the URL can be generated and sent. The format of the URL is:
https://www.machinesense.net/jsapi/v1/client/?i=[SessID]&l=[Lang]&s=[Scene]
In the above URL:
nld-id (for Dutch ID-card) or nld-pass (for Dutch passport).
This option is a bit more flexible and allows partners to build own user interface arround Machine Sense core WASM and it's
internal interface.
In this case, WASM is opened in an IFrame.
The URL is similar to the Direct Link, but here it points to the partners page.
The partner's backend calls Machine Sense Backend API to get Session ID. After acquiring this parameter, the URL can be generated and sent. The format of the URL is:
https://www.your-company.com/kycpage.html?i=[SessID]&l=[Lang]&s=[Scene]
In the above URL:
nld-id (for Dutch ID-card) or nld-pass (for Dutch passport).
When partner's page opens, it should collect the parameters from the URL and pass them to the IFrame forming the following URL:
https://www.machinesense.net/jsapi/v1/client/?i=[SessID]&l=[Lang]&s=[Scene]
Thus, when instantiating WASM in your IFrame, the IFrame URL is similar to the Direct Link option.
Once the process is finished, the Machine Sense interface inside the IFrame will post the message to the parent partners page.
The client page can then perform various steps and/or adjust the interface. The message will have the following format:
{
"machinesense": {
i: [Session ID],
s: [Scene name - used in the process],
l: [Language]
},
ok: 0/1/2
}
The message can be accepted by a standard event listener:
window.addEventListener('message', (event) => {
if (!event) return;
if (!event.data) return;
if (!event.data['machinesense']) return;
if (!event.data['ok']) {
// we have error
// 1 - unknown error
// 2 - permission for the camera not given
return;
}
//we have success
}
Machine Sense offers full JS API for client side integration. This is the most flexible option that requires additional development and integration.
The partner's backend calls Machine Sense Backend API to get Session ID. After acquiring this parameter, the API needs to be included as follows:
<script defer="" src="https://www.machinesense.net/jsapi/v1/kyc.js"></script>
<link rel="stylesheet" href="https://www.machinesense.net/jsapi/v1/kyc.css">
The included files give access to the MachineSense API and WASM component. The API can be used by creating instance
of the KYC WASM object.
const kyc = new this.KYC([Session ID]);
[Session ID] parameter is acquired by call to the Machine Sense Backend API.
Once the API object is created it can be started:
kyc.start(options);
Options represents an object with the following properties:
{
scenario: [Scene name],
container: [container],
successSound: [Sound URL],
i18n: [i18n],
onError: [error function],
onSuccess: [success function]
}
The above options are:
document.getElementById('kyc_container'); ).
{
"Line up the barcode inside the frame":
"Line up the barcode inside the marked frame",
"Present the front side of ID card":
"Present the front side of the card",
"Present the backside of ID card":
"Present the backside of the card"
}