zkMe Dochub
GitHubTwitterDiscord
  • zkMe Network
  • Learn about zkMe Network
    • Introduction
    • Try a Demo
    • High Level Architectural Overview
      • High Level User Stories
      • zkMe Protocol Components
        • zkMe zkVault
        • zkMe DID Method
        • zkMe Credential Suites
        • zkMe Self-Sovereign Identity
    • Vision, Mission & Design Philosophy
    • Value Propositions & Use Cases
  • Verify with zkMe Protocol
    • Integration Checklist
      • zkMe Dashboard Setup
      • zkMe Supported Chains Overview
      • zkMe Protocol Smart Contract
    • Integration Guide
      • JavaScript SDK
        • zkKYC - Compliance Suite
        • MeID - Anti-Sybil Suite
        • Me - Profiling Suite
      • zkMe API
        • zkKYC - Compliance Suite
          • Verify zkKYC Status
          • Get KYT Results
      • Platform Integration
        • QuestN Integration
      • Smart Contract Verification
        • Compliance Suite
      • Customize Widget UI
    • zkKYC - Compliance Suite
      • zkMe zkKYC Levels
      • Regulatory Frameworks
        • EU - MiCA/TFR Regulations
        • US - Crypto Regulations
        • UK - Crypto Regulations
      • zkKYC Credentials
        • Proof-of-Citizenship (zkPoC)
        • Proof-of-Location (zkPoL)
        • Proof-of-Accredited-Investor (zkPoAI)
        • AML Check (AMLMe)
        • Know Your Transaction (KYT)
          • KYT Supported Scope
        • Know Your Business (KYB)
    • MeID - Anti-Sybil Suite
      • CKKS Homomorphic Encryption
      • DID Creation
      • MeID Credentials
        • MeID
    • Me - Profiling Suite
      • MeScores Credentials
        • zkCredit Score
        • zkSocial Network
        • zkDAO Management
        • zkGaming Status
    • zkMe Roadmap
  • Explore More
    • zkMe Bug Bounty Program
    • zkMe Brand Kit
    • zkMe Identity Hub
    • FAQ
    • Glossary
    • Link
      • GitHub
      • X / Twitter
      • Medium
      • YouTube
      • LinkedIn
      • Discord
      • Blog
    • Privacy Policy
Powered by GitBook
On this page
  • Use Case
  • zkMe-Widget KYC Process
  • Interaction Instructions
  • Integration via NPM
  • Installation
  • Getting Started
  • Helper functions
  • verifyKycWithZkMeServices()
  • How to Generate an Access Token with API_KEY
  • ZkMeWidget instance methods
  • Common Response & Exceptions
  1. Verify with zkMe Protocol
  2. Integration Guide
  3. JavaScript SDK

zkKYC - Compliance Suite

zkKYC SDK - Simply execute KYC progress using the RedirectURL as the src-attribute value for the iFrame.

PreviousJavaScript SDKNextMeID - Anti-Sybil Suite

Last updated 1 month ago

Use Case

To reduce the development cost for the project side, the project can use zkKYC capability by simply accessing the link. Users can complete full KYC verification directly on the web/H5, reducing user churn by minimizing the need to navigate to another page.


zkMe-Widget KYC Process

Step 1: Enter the service authorization Widget page; the user confirms and goes to the next step

Step 2: E-mail verification login

Step 3: Verify the SBT to confirm that it is authenticated

Step 4: Depending on the KYC configuration of the project, determine whether the user needs to undergo different verification processes.


Interaction Instructions


Integration via NPM

Installation

pnpm add @zkmelabs/widget

# or
yarn add @zkmelabs/widget

# or
npm install @zkmelabs/widget

Getting Started

Step 1. Import styles

import '@zkmelabs/widget/dist/style.css'

Step 2. Create a new ZkMeWidget instance

import { ZkMeWidget, type Provider } from '@zkmelabs/widget'

const provider: Provider = {
  async getAccessToken() {
    // -------------------------TODO-------------------------
    // Request a new token from your backend service and return it to the widget.
    // For the access token, see docs.zk.me/zkme-dochub/verify-with-zkme-protocol/integration-guide/javascript-sdk/zkkyc-compliance-suite#how-to-generate-an-access-token-with-api_key
    // ------------------------------------------------------
    return fetchNewToken()
  },

  async getUserAccounts() {
    // -------------------------TODO-------------------------
    // If your project is a Dapp,
    // you need to return the user's connected wallet address.
    const userConnectedAddress = await connect()
    return [userConnectedAddress]

    // If not,
    // you should return the user's e-mail address, phone number or any other unique identifier.
    //
    // return ['email address']
    // or
    // return ['phone number']
    // or
    // return ['unique identifier']
    // ------------------------------------------------------
  },

}

const zkMeWidget = new ZkMeWidget(
  // -------------------------TODO-------------------------
  appId, // This parameter means the same thing as "mchNo"
  'YourDappName',
  '137', // chainId. No changes are needed here if the account is configured for cross-chain.
  provider,
  {
      lv: 'zkKYC'
      // For other options, please refer to the table below
  }
  // ------------------------------------------------------
)
import { ZkMeWidget, type Provider } from '@zkmelabs/widget'

const provider: Provider = {
  async getAccessToken() {
    // -------------------------TODO-------------------------
    // Request a new token from your backend service and return it to the widget.
    // For the access token, see docs.zk.me/zkme-dochub/verify-with-zkme-protocol/integration-guide/javascript-sdk/zkkyc-compliance-suite#how-to-generate-an-access-token-with-api_key
    // ------------------------------------------------------
    return fetchNewToken()
  },

  async getUserAccounts() {
    // -------------------------TODO-------------------------
    // If your project is a Dapp,
    // you need to return the user's connected wallet address.
    const userConnectedAddress = await connect()
    return [userConnectedAddress]

    // If not,
    // you should return the user's e-mail address, phone number or any other unique identifier.
    //
    // return ['email address']
    // or
    // return ['phone number']
    // or
    // return ['unique identifier']
    // ------------------------------------------------------
  },

  // -------------------------TODO-------------------------
  // According to which blockchain your project is integrated with,
  // choose and implement the corresponding methods as shown below.

  // EVM
  async delegateTransaction(tx) {
    const txResponse = await signer.sendTransaction(tx)
    return txResponse.hash
  },

  // Cosmos
  async delegateCosmosTransaction(tx) {
    const txResponse = await signingCosmWasmClient.execute(
      tx.senderAddress,
      tx.contractAddress,
      tx.msg,
      'auto'
    )
    return txResponse.transactionHash
  },

  // Aptos
  async delegateAptosTransaction(tx) {
    const txResponse = await aptos.signAndSubmitTransaction(tx)
    return txResponse.hash
  },

  // TON
  async delegateTonTransaction(tx) {
    const { boc } = await tonConnectUI.sendTransaction({
      validUntil: Date.now() + 5 * 60 * 1000, // You can customize this value
      messages: [tx]
    })
    const { hash } = Cell.fromBase64(boc)
    return hash().toString('hex')
  },

  // ...
  // See the Provider interface definition for more details on other chains.
  // ------------------------------------------------------
}


const zkMeWidget = new ZkMeWidget(
  // -------------------------TODO-------------------------
  appId, // This parameter means the same thing as "mchNo"
  'YourDappName',
  chainId,
  provider,
  {
      lv: 'zkKYC'
      // For other options, please refer to the table below
  }
  // ------------------------------------------------------
)

NOTE: The specific configuration for the "option" parameter is shown in the table below

Param
Type
Description

options.lv

VerificationLevel?

"zkKYC" or "MeID", default "zkKYC"

options.programNo

string?

If you have activated multiple programs running in parallel, please pay attention to this setting:

options.theme

Theme?

"auto", "light" or "dark", default "auto".

options.locale

Language?

"en" or "zh-hk", default "en".

Step 3. Listen to the kycFinished widget events to detect when the user has completed the zkKYC process.

function handleFinished(results) {
  const { isGrant, associatedAccount } = results

  if (
    isGrant &&
    associatedAccount === userConnectedAddress.toLowerCase()
  ) {
    // -------------------------TODO-------------------------
    // Prompts the user that zkKYC verification has been completed
    // ------------------------------------------------------
  }
}

zkMeWidget.on('kycFinished', handleFinished)

Step 4. Launch the zkMe widget and it will be displayed in the center of your webpage.

// This is the code to launch our widget on your page
button.addEventListener('click', () => {
  zkMeWidget.launch()
})

Helper functions

verifyKycWithZkMeServices()

Before launching the widget, you should check the zkKYC status of the user and launch the widget when the check result is false.

import { verifyKycWithZkMeServices } from '@zkmelabs/widget'

// zkKYC
const { isGrant } = await verifyKycWithZkMeServices(
  appId,
  userAccount,
  // Optional configurations are detailed in the table below
  options
)
Param
Type
Description

appId

string

This parameter means the same thing as "mchNo"

userAccount

string

The userAccount info (such as wallet address, email, phone number, or unique identifier) must match the format of accounts returned by provider.getUserAccounts.

options.programNo

string?

How to Generate an Access Token with API_KEY

To use your API_KEY to obtain an accessToken, you will need to make a specific HTTP request. Here's how you can do it:

a. Endpoint: Send a POST request to the token exchange endpoint.

POST https://nest-api.zk.me/api/token/get

Please remember to modify the Content-Type in the request header to application/json. Failing to do so might result in a Parameter Error response.

b. Request Body:

Parameter Name
Required
Type
Desc

apiKey

True

string

The API_KEY provided by zkMe.

appId

True

string

A unique identifier (mchNo) to DApp provided by zkMe.

apiModePermission

True

number

0 - email login (Only support email login)

lv

True

number

1 - zkKYC 2 - MeID

c. Response

Success
{
    "code": 80000000,
    "data": {
        "accessToken": "8641259808779c53de65c3698e42b402b112cfe3856202189c37eae9f0b23babbcc1429ea9adcb52283dca4dab024a640651f855d8c78c7bde308f721a6e0cb80d51dab7c775ebfe0ae74eb9ab02f503094a9b2a2e2aeabf70e03a0cac9773a93dba743ca0dc3fa4af77375351bc48f76515d72dbee3a8bd5c034e6ffb94bd97"
    },
    "msg": "success",
    "timestamp": 1691732474552
}
Exception (AppId and API_KEY not matched)
{
    "code": 81000014,
    "data": null,
    "msg": "AppID and API Key do not match. Access token generation failed",
    "timestamp": 1691732568774
}
Exception (Parameter Error)
{
    "code": 80000002,
    "data": null,
    "msg": "parameter error",
    "timestamp": 1691732593484
}
Exception (System Error)
{
    "code": 80000001,
    "data": null,
    "msg": "system error",
    "timestamp": 1691732593484
}

ZkMeWidget instance methods

launch()

Launch the zkMe widget and it will be displayed in the center of your webpage.

launch(): void
on()

Listen to zkMe widget events.

on(event: 'kycFinished', callback: KycFinishedHook): void;
on(event: 'close', callback: () => void): void;
switchChain()

If your DApp integrates multiple chains, use this method to synchronize the new chain to the zkMe widget when the user switches chains in your DApp.

switchChain(chainId: string): void
hide()

Hide the zkMe widget.

hide(): void
destroy()

Remove the message event listener registered by the zkMe widget from the window and destroy the DOM node.

destroy(): void

Common Response & Exceptions

Success

If the user has passed the KYC verification and the user’s SBT could be accessed by your project, the following interface will be seen. Meanwhile, there will be a message with KYC results sent to your DApp.

Camera Permission Denied Error

The following screen will be displayed for possible issues such as the user denying browser camera access or not having a camera on the device.

OCR Scan Error

The following screen will be displayed when an exception occurs during the OCR process.

Face Recognition Error

The following screen will be displayed for possible problems such as eyes closed detected, art mask detected etc.

Face Mismatch Error

The following screen will be displayed when the face could not match the uploaded ID.

Faceprint Mismatch Error

The following screen will be displayed for the possible problem that the fully homomorphically encrypted faceprint does not match the one associated with this MeID.

Faceprint Recognition Server Error

The following screen will be displayed when something goes wrong on the faceprint recognition server.

Unknown Error

The following screen will be displayed when something goes wrong not listed above.

You can refer to and please make sure to use the latest version.

The param can be found in and please make sure the program is enabled. The SDK will take the number of the first activated program as the default value if this parameter is not provided in the code.

If you have activated multiple programs running in parallel, please pay attention to this setting: The param can be found in and please make sure the program is enabled. The SDK will take the number of the first activated program as the default value if this parameter is not provided in the code.

If the level of your Dashboard account is not Cross-Chain, then you can also query users' zkKYC status from zkMe Verify & Certify Smart Contract .

API_KEYcan be found in of the Integration on the zkMe Dashboard.

@zkmelabs/widget
here
the Configuration section
Dashboard
Dashboard