SDK Integration

Anti-Sybil SDK - A rapid and privacy-preserving solution to combat bot and sybil attacks by using the RedirectURL as the src-attribute value for the iFrame.

Use Case

When you need to protect a website or application from automated attacks, you can use anti-bot mechanisms. These attacks can result in malicious behavior, such as spamming, data theft, or network disruption. Anti-bot technology is designed to identify and block these attacks to ensure that only real human users can access your website or application.

In this case, users are required to undergo facial liveliness detection to prove that they are real human users. This detection requires users to perform specific actions or expressions in front of a camera to prove that they are genuine humans and not automated programs. This technology can help prevent automated attacks and fraud, and increase the security and reliability of your website or application.

---

zkMe-Widget MeID Process

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

Step 2: E-mail verification login / Wallet address login

Step 3: Verify that the user has authorized MeID

Step 4: Based on the outcomes of the initiated query, a determination is made regarding whether to commence the authentication process for the specified user.

---

Interaction Instructions

---

Integration via NPM

You can refer to @zkmelabs/widget and please make sure to use the latest version.

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() {
        // Request a new token from your backend service and return it to the widget.
        // For the access token, please refer to Usage Example -> Exchanging API_KEY for Access Token below
        return fetchNewToken()
    },
    
    async getUserAccounts() {
        // If your project is a Dapp,
        // you need to return the user's connected wallet address.
        if (!userConnectedAddress) {
            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(
    appId, // This parameter means the same thing as "mchNo"
    'YourDappName',
    chainId,
    provider,
    options
)

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

Para	Type	Description
options.lv	VerificationLevel?	"zkKYC" or "Anti-Sybil", default "zkKYC"

Step 3. Listen to the finished widget events to detect when the user has completed the MeID process

import { verifyWithZkMeServices } from '@zkmelabs/widget'

function handleFinished(verifiedAccount: string) {
// We recommend that you double-check this by calling
// the functions mentioned in the "Helper functions" section.
    if (
    verifiedAccount === userConnectedAddress
    ) {
        // Anti-Sybil(MeID)
        const results = await verifyWithZkMeServices(appId, userConnectedAddress, 'Anti-Sybil')
        
        if (results) {
        // Prompts the user that MeID verification has been completed
        }
    }
}

zkMeWidget.on('finished', handleFinished)

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

zkMeWidget.launch()

---

Helper functions

verifyWithZkMeServices

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

import { verifyWithZkMeServices } from '@zkmelabs/widget'

const results: boolean = await verifyWithZkMeServices(
    appId,
    userAccount
)

if (!results) {
    zkMeWidget.launch()
}

Param	Type	Description
appId	string	This parameter means the same thing as "mchNo"
userAccount	string	Same value as in provider.getUserAccounts
lv	VerificationLevel?	"zkKYC" or "Anti-Sybil", default "zkKYC"

Exchanging API_KEY for Access Token

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 1-wallet address login
lv	True	number	The parameter must be passed and always be 2.

API_KEY you can get this from the zkMe Biz dashboard.

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
}

---

Response & Exceptions

Success

If the user has passed the liveness and uniqueness verification, the following interface will be seen.

Note:

The finished callback function will be fired after the interface is displayed.

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.

Face Recognition Error

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

Existing Faceprint Error

The following screen will be displayed for the possible problem that the user’s faceprint is similar to another user’s.

Faceprint Mismatch Error

The following screen will be displayed for the possible problem that the fully homomorphically encrypted faceprint does not match the information in the credential which verified with this account. This error can only occur if the user has done the KYC process.

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.

---

Smart Contract Workflow

Regarding smart contract workflow, please refer to this