NPM Integration (outdated)
Learn how to integrate Incode Web SDK in your web applications
Overview
This guide explains how to verify an individual using the Web SDK. The app will ask users to scan their ID and take a selfie, which are modules included in the Standard Flow. If you are familiar with NPM for dependency management, this guide is a good place to start.
After completing the guide, your app will include Web SDK's auto capture cameras. Auto capture makes it easy for customers to scan their ID document and take a selfie. The essence of auto capture is that it will take the photo for the customer, when conditions are optimal. When conditions are not optimal the SDK will display feedback advising the customer what to do. The SDK also will prompt a user to retake a photo, if photo quality were determined to be not optimal.
Considerations for choosing an NPM Web SDK integration are:
- You are familiar with NPM
- You are prepared to host your own app
- You would like to control the sequence of Incode's identity verification screens
- You would like to alter the text on screens
- You would like to control the UI between module screens
- You would like the browser's address bar to display your domain name
- You are prepared to update the Web SDK when new releases come out
- You are prepared to write code to implement flow settings and control the UI/UX
Step 1: Create the project structure
Create a folder named app and inside the app folder add these files.
Project:
app
|
----index.html
|
----style.css
|
----main.js
|
----package.json
|
----.env
Once this is done, update the index.html file with the following code:
index.html:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="theme-color" content="#000000" />
<title>JS Best Practice Example</title>
</head>
<body>
<noscript>You need to enable JavaScript to run this app.</noscript>
<div id="root" class="app-content">
<div id="camera-container">
<button id="start" class="app-btn">Get Started</button>
</div>
</div>
<script type="module" src="/main.js"></script>
</body>
</html>
Step 2: Add the Web SDK and libraries
Now add the Web SDK dependency to your package.json file. You may notice a few extra non-Incode dependencies. The Vite libs are used to make building, compiling and running the app easier.
package.json
{
"name": "javascript-best-practice",
"version": "1.0.0",
"description": "",
"main": "index.js",
"private": true,
"type": "module",
"author": "Incode",
"license": "",
"scripts": {
"start": "vite",
"dev": "vite",
"build": "vite build",
"serve": "vite preview"
},
"dependencies": {
"@incodetech/welcome": "1.63.0-beta.0"
},
"browserslist": {
"production": [
">0.2%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
},
"devDependencies": {
"@vitejs/plugin-react": "^3.0.0",
"vite": "^4.0.1",
"vite-plugin-mkcert": "^1.13.4",
"vite-plugin-svgr": "^2.4.0",
"vite-tsconfig-paths": "^4.0.3"
}
}
Now run the following command in your terminal to install the Web SDK.
npm install
Aways get the latest version of the Web SDK
Check out the release notes to ensure you are using the lastest version of the Web SDK. Alternatively, use our NPM version tabto find the latest release.
Step 3: Initialize the Web SDK
To initialize the Web SDK you will need to import the create() method. Once imported, the create() method needs to know which Incode environment to use (DEMO or SASS).
You can do this by updating the .env file. Variables assigned in the .env will be merged into your app when calling the NPM scripts npm run dev
or npm run build
.
VITE_INCODE_API_URL = https://demo-api.incodesmile.com/0
Next import the create() method and initialize the SDK. To do this edit your main.js as follows. For context, line 3 will receive the value of the of https://demo-api.incodesmile.com/0
. Create will return a large object which pretty much contains all methods available in the Web SDK.
import { create } from '@incodetech/welcome';
let incode;
const incode = onBoarding = await create({
apiURL: apiURL
});
async function app() {
try {
const apiURL = import.meta.env.VITE_INCODE_API_URL
incode = create({
apiURL: apiURL,
theme: {},
});
// Incode Web SDK needs to preload resources before being usable
await incode.warmup();
} catch (e) {
console.dir(e);
container.innerHTML = "<h1>Something Went Wrong</h1>";
throw e;
}
}
document.addEventListener("DOMContentLoaded", app);
Pro Tip: If you would like to update the strings used in the Web SDK you can supply your own string values by adding a translations parameter within the create() method.
modify string recipe
Step 4: Create a session
A session object includes an access token which is used to authenticate requests to your Incode environment. As a best practice, Web SDK clients should fetch a session from a server. This server should be maintained by your organization.
To complete Step 4, please setup and run a sample server. Each sample server includes setup instructions and has code to fetch an access token. Once the sample server is running you can fetch your access token using the sample server's /startendpoint and create a session object.
Setup a quick start sample server (15-20 minutes): Quick Start Sample Servers
Next update your .env file and your main.js to communicate with your sample server.
Edit your .env to include the HTTPS URL to your sample server.
VITE_INCODE_API_URL = https://demo-api.incodesmile.com/0
VITE_YOUR_INCODE_TOKEN_SERVER_URL = https://69c0-76-95-83-56.ngrok-free.app
Edit your main.js file to fetch the token and create a session object. The session object will be used in the remaining steps.
import { create } from '@incodetech/welcome';
let incode;
let session;
const container = document.getElementById("camera-container");
async function startOnboardingSession() {
tokenServerURL = import.meta.env.VITE_YOUR_INCODE_TOKEN_SERVER_URL;
const response = await fetch(`${tokenServerURL}/start`);
const session = await response.json();
return session;
}
async function app() {
try {
const apiURL = import.meta.env.VITE_API_URL;
incode = window.OnBoarding.create({
clientId: clientId,
theme: {},
});
// Incode Web SDK needs to preload resources before being usable
await incode.warmup();
// Create a session object
session = await startOnboardingSession();
// TODO: Begin calling standard flow modules
} catch (e) {
console.dir(e);
container.innerHTML = "<h1>Something Went Wrong</h1>";
throw e;
}
}
document.addEventListener("DOMContentLoaded", app);
Step 5: Add device fingerprinting
Next add the device fingerprint module by adding a reference to sendFingerprint(). While there is no UI for this module, this one is important to include because it adds location information and metadata about the device which is useful in data analytics.
Next update your main.js file to look like this.
import { create } from '@incodetech/welcome';
let incode;
let session;
const container = document.getElementById("camera-container");
async function startOnboardingSession() {
tokenServerURL = import.meta.env.VITE_YOUR_INCODE_TOKEN_SERVER_URL;
const response = await fetch(`${tokenServerURL}/start`);
const session = await response.json();
return session;
}
async function app() {
try {
const apiURL = import.meta.env.VITE_API_URL;
incode = window.OnBoarding.create({
clientId: clientId,
theme: {},
});
// Incode Web SDK needs to preload resources before being usable
await incode.warmup();
// Create a session object
session = await startOnboardingSession();
incode.sendFingerprint({ token: session.token }).then((response) => {
console.log(response.success);
//TODO: Implement next module
});
} catch (e) {
console.dir(e);
container.innerHTML = "<h1>Something Went Wrong</h1>";
throw e;
}
}
document.addEventListener("DOMContentLoaded", app);
Step 6: Add ID modules
Now implement the Standard Flow's ID capture and ID validation. ID validation includes three parts - front ID capture, back ID capture and process ID. In some cases back ID capture can be skipped, if a user scanned a passport. A passport is a font side only document.
Add the following code to main.js to enable ID validation.
import { create } from '@incodetech/welcome';
let incode;
let session;
const container = document.getElementById("camera-container");
function showError(e=null) {
container.innerHTML = "<h1>There was an error</h1>";
console.log(e)
}
function captureIdFrontSide() {
incode.renderCamera("front", container, {
onSuccess: captureIdBackSide,
onError: showError,
token: session,
numberOfTries: 3,
showTutorial: true,
showCustomCameraPermissionScreen: true,
});
}
function captureIdBackSide() {
incode.renderCamera("back", container, {
onSuccess: processId,
onError: showError,
token: session,
numberOfTries: 3,
showTutorial: true,
showCustomCameraPermissionScreen: true,
});
}
function processId() {
return incode
.processId({ token: session.token })
.then(() => {
captureSelfie();
})
.catch((error) => {
console.log(error);
});
}
async function startOnboardingSession() {
tokenServerURL = import.meta.env.VITE_YOUR_INCODE_TOKEN_SERVER_URL;
const response = await fetch(`${tokenServerURL}/start`);
const session = await response.json();
return session;
}
async function app() {
try {
const apiURL = import.meta.env.VITE_API_URL;
incode = window.OnBoarding.create({
clientId: clientId,
theme: {},
});
// Incode Web SDK needs to preload resources before being usable
await incode.warmup();
// Create a session object
session = await startOnboardingSession();
incode.sendFingerprint({ token: session.token }).then((response) => {
console.log(response.success);
//Implement Front ID Capture
captureIdFrontSide();
});
} catch (e) {
console.dir(e);
container.innerHTML = "<h1>Something Went Wrong</h1>";
throw e;
}
}
document.addEventListener("DOMContentLoaded", app);
Step 7: Add Selfie modules
In this step you will capture the customer's selfie. Additionally you will tell the server to process the face. Once a face is processed on the server you will discover if the ID face matches the customer's selfie and you will also find out if the selfie is of a real person, which is determined through a passive liveness check.
Edit the main.js file to look like the following:
import { create } from '@incodetech/welcome';
let incode;
let session;
const container = document.getElementById("camera-container");
function showError(e=null) {
container.innerHTML = "<h1>There was an error</h1>";
console.log(e)
}
function renderSelfieCamera() {
incode.renderCamera("selfie", container, {
onSuccess: processFace,
onError: showError,
token: session,
numberOfTries: 3,
noWait: true
});
}
function processFace() {
const response = await incode.processFace({
token: session
});
}
function captureIdFrontSide() {
incode.renderCamera("front", container, {
onSuccess: captureIdBackSide,
onError: showError,
token: session,
numberOfTries: 3,
showTutorial: true,
showCustomCameraPermissionScreen: true,
});
}
function captureIdBackSide() {
incode.renderCamera("back", container, {
onSuccess: processId,
onError: showError,
token: session,
numberOfTries: 3,
showTutorial: true,
showCustomCameraPermissionScreen: true,
});
}
function processId() {
return incode
.processId({ token: session.token })
.then(() => {
captureSelfie();
})
.catch((error) => {
console.log(error);
});
}
async function startOnboardingSession() {
tokenServerURL = import.meta.env.VITE_YOUR_INCODE_TOKEN_SERVER_URL;
const response = await fetch(`${tokenServerURL}/start`);
const session = await response.json();
return session;
}
async function app() {
try {
const apiURL = import.meta.env.VITE_API_URL;
incode = window.OnBoarding.create({
clientId: clientId,
theme: {},
});
// Incode Web SDK needs to preload resources before being usable
await incode.warmup();
// Create a session object
session = await startOnboardingSession();
incode.sendFingerprint({ token: session.token }).then((response) => {
console.log(response.success);
//Implement Front ID Capture
captureIdFrontSide();
});
} catch (e) {
console.dir(e);
container.innerHTML = "<h1>Something Went Wrong</h1>";
throw e;
}
}
document.addEventListener("DOMContentLoaded", app);
Step 8: Get Identity Verification Results
The results of the Identity Verification session are available instantly (in about 3 seconds following the selfie capture). Results will include the following:
- ID Validation score results
- All text, type and information found on the ID document
- Liveness detection score results
- Face Recognition score results
Results can be accessed in two ways:
- Use the dashboard to review and obtain results
- Use a Web Hook to obtain results
To learn how to get results using the dashboard review this section of our documentation. To learn how to create a Web Hook review this foundation section using Getting results.
Conclusion
If you want a complete end-to-end NPM integration example, please checkout our GitHub.
Visit our GitHub website to download a complete end-to-end IFrame example, which was designed for production use cases. -> Goto GitHub
Updated 2 months ago