zkKYC SDK - Simply execute KYC progress using the RedirectURL as the src-attribute value for the iFrame.
Use Case
To reduce the development cost for the project side, the project can use zkKYC capability by simply accessing the link. Users can achieve full KYC capability on the web/H5, reducing the possibility of 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
You can refer to @zkmelabs/widget and please make sure to use the latest version.
import { ZkMeWidget,type Provider } from'@zkmelabs/widget'constprovider:Provider= {asyncgetAccessToken() {// -------------------------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/zkkyc-compliance-suite/zkkyc-integration-guide/sdk-integration#how-to-generate-an-access-token-with-api_key
// ------------------------------------------------------returnfetchNewToken() },asyncgetUserAccounts() {// -------------------------TODO-------------------------// If your project is a Dapp,// you need to return the user's connected wallet address.constuserConnectedAddress=awaitconnect()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']// ------------------------------------------------------ },}constzkMeWidget=newZkMeWidget(// -------------------------TODO------------------------- appId,// This parameter means the same thing as "mchNo"'YourDappName','0x89', provider, { lv:'zkKYC'// For other options, please refer to the table below }// ------------------------------------------------------)
import { ZkMeWidget,type Provider } from'@zkmelabs/widget'constprovider:Provider= {asyncgetAccessToken() {// -------------------------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/zkkyc-compliance-suite/zkkyc-integration-guide/sdk-integration#exchanging-api_key-for-access-token
// ------------------------------------------------------returnfetchNewToken() },asyncgetUserAccounts() {// -------------------------TODO-------------------------// If your project is a Dapp,// you need to return the user's connected wallet address.constuserConnectedAddress=awaitconnect()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.// EVMasyncdelegateTransaction(tx) {consttxResponse=awaitsigner.sendTransaction(tx)returntxResponse.hash },// CosmosasyncdelegateCosmosTransaction(tx) {consttxResponse=awaitsigningCosmWasmClient.execute(tx.senderAddress,tx.contractAddress,tx.msg,'auto' )returntxResponse.transactionHash },// AptosasyncdelegateAptosTransaction(tx) {consttxResponse=awaitaptos.signAndSubmitTransaction(tx)returntxResponse.hash },// ...// See the Provider interface definition for more details on other chains.// ------------------------------------------------------}constzkMeWidget=newZkMeWidget(// -------------------------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:
The param can be found in Dashboard 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.
options.theme
Theme?
"auto", "light" or "dark", default "auto". This option must match the 'Set your color mode' settings in the Dashboard. For widget UI customization, please refer to: Customize Widget UI.
Step 3. Listen to the kycFinished widget events to detect when the user has completed the zkKYC process.
asyncfunctionhandleFinished(results) {const { isGrant,associatedAccount } = resultsif ( 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 pagebutton.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'// zkKYCconst { isGrant } =awaitverifyKycWithZkMeServices( 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
Same value as in provider.getUserAccounts
options.programNo
string?
If you have activated multiple programs running in parallel, please pay attention to this setting:
The param can be found in Dashboard 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 here.
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.
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.