@web3auth/kyc-embed

KYC Embed

Demo

https://demo-kyc.web3auth.io

How it works:-

This sdk comes with two components:-

1. Liveness embed:- This component allows your app to verify liveness of a user and to filter out bots from accessing your app. This component works by verify user's liveness by doing a live user's selfie video verification test.

   Additionally this component provides a way to check security of device connection using a optional captcha. Note:- Using captcha is a optional.

   You can use this component in both with or without wallet connection. If you want user to verify the liveness only once than it suggested to user it with any wallet connection. But if you want user to verify liveness on every new device session then non wallet login flow can be used.

2. Kyc embed:- This component allows your app to verify user's kyc data. This component is currently only works for india region and supports verification of documents like:- AADHAR and PAN

Liveness Check Usage

Before you begin, you need a Web3auth Client ID to use LivenessCheck SDK. Please create one in web3auth dashboard if you don't have one.

Prerequisites

// package.json

// Copy the kyc-embed package and install the web3auth and web3 packages if you are planning to include authentication

"dependencies": {
  "@web3auth/kyc-embed": "^0.1.0",
  "@web3auth/base": "^8.0.0",
  "@web3auth/ethereum-provider": "^8.0.1",
  "@web3auth/modal": "^8.0.1",
  "web3": "^4.6.0"
},

// globals.ts

// Polyfill `Buffer` which is used in the iframe communication and inject `process` to access environment variables in Vite

import { Buffer } from "buffer";
import process from "process";

window.global = globalThis;
globalThis.Buffer = globalThis.Buffer || Buffer;
process.env = { ...process.env, ...(globalThis.process?.env || {}) };
globalThis.process = process;

Basic Usage (Without wallet and authentication)

import "./globals"
import { LivenessEmbed } from  "@web3auth/kyc-embed";
import { WEB3AUTH_NETWORK } from "@web3auth/base";

// 1. create an instance
const embedInstance = new LivenessEmbed({
  web3AuthClientId:  <YOUR_WEB3AUTH_CLIENT_ID>,
  web3AuthNetwork:  WEB3AUTH_NETWORK.SAPPHIRE_DEVNET,
});

// 2. initialize
await embedInstance.init();

// 3. start liveness check
embedInstance.initLivenessCheck({
  // this field is intended for the usage before login
  // setting this to `true` will allow users to access the liveness check without logging in
  // for the liveness check usage after login, please see the next section
  allowUnauthenticatedAccess: true,
});

Usage with authenticated users/wallets

You can authenticate with any EIP-1993 wallet. In this example code, we're using @web3auth/modal PNP modal SDK to login.

import "./globals"
import { LivenessEmbed } from  "@web3auth/kyc-embed";
import { CHAIN_NAMESPACES, WEB3AUTH_NETWORK } from "@web3auth/base";
import  { Web3Auth }  from  "@web3auth/modal";
import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
...
const WEB3AUTH_CLIENT_ID = <YOUR_WEB3AUTH_CLIENT_ID>;
// 1. create and initialize LivenessEmbed instance
const embedInstance = new LivenessEmbed({ ... });
await embedInstance.init();
...
...
// 2. LOGIN
// setup config
const chainConfig = {
  chainId: "0x1", // Please use 0x1 for Mainnet
  rpcTarget: "https://rpc.ankr.com/eth",
  chainNamespace: CHAIN_NAMESPACES.EIP155,
  displayName: "Ethereum Mainnet",
  blockExplorerUrl: "https://etherscan.io/",
  ticker: "ETH",
  tickerName: "Ethereum",
  logo: "https://images.toruswallet.io/eth.svg",
};
// initialize a provider
const privateKeyProvider = new EthereumPrivateKeyProvider({
  config: { chainConfig: config.chainConfig },
});
// create web3auth login modal instance
const web3auth = new Web3Auth({
  clientId: WEB3AUTH_CLIENT_ID,
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_DEVNET,
  privateKeyProvider: privateKeyProvider,
});
// initiate login modal
await web3auth.initModal();
...
...
// 3. Authenticate
// open login modal if user is not logged in
if (!web3auth.connected) {
  await web3auth.connect();
}
// generate the id token which will be used during the liveness check requests
const web3 = new Web3(web3auth.provider);
const accounts = await web3.eth.getAccounts();
// fetch the message from the server
const authMsg = await embedInstance.getAuthMessage({ address: accounts[0] });
// sign the message
const signedMessage = await web3.eth.personal.sign(authMsg?.message ?? "", accounts[0], "test password");
// get the authorization token. The authentication token will be saved in the LivenessEmbed State, so you don't need to pass around the token
const  { token } = await embedInstance.verifyAuthSignature({ address:accounts[0], signature: signedMessage });
...
...
// 4. Start the liveness check
await embedInstance.initLivenessCheck();

Check liveness status

For authenticated mode, you can call getLivenessCheckStatus method to check the status of the Liveness Check.

// NOTE:
// you must be in the `Authenticated` mode (`allowUnauthenticatedAccess: false,`)
// in order to use this method properly.

// under the hood, this method will use `Authentication Token` stored in the Embed State (refer to step 3 in Authenticated Usage)
let status = await livenessEmbed.getLivenessCheckStatus();

The below is the sample of Liveness Check Success Response

{
  "id": 40,
  "created_at": "2024-03-25T07:27:08.000Z",
  "updated_at": "2024-03-25T07:27:19.000Z",
  "liveness_analysis_status": "Success",
  "public_address": "0x750882A476DCC8c80f725C139e444143da9f8dBb",
  "client_id": "....",
  "retry": 2
}

Subscribe to UI Events

You can optionally call the subscribeEvents method to get the Liveness UI Events updates (such as success, failure, cancelled etc..)

// you can call embed's subscribeEvents() method to listen to the Liveness UI Events
// and perform any relevant actions by providing callback function as a method parameter
function cb(method:string,params?:any) {
  ...
  if (method === "on_cancelled_liveness") {
    console.log("user has cancelled the liveness check before finished");
    // do your things
    ...
  }
}
// call this method after `embedInstance.init()`
embedInstance.subscribeEvents(cb);

Enable Captcha

You can choose to use our built-in captcha, or use your own captcha system, or not use any captcha.

// Use Web3Auth built-in captcha
embedInstance.initLivenessCheck({ enableCaptcha: true });

// Use your own captcha or do not use any captcha
embedInstance.initLivenessCheck({ enableCaptcha: false /* or undefined */ });

Examples

Checkout the demo application for how you can integrate the Liveness Check in your frontend application.

Api References

Coming Soon