Captcha:Integration guide

Web and H5 integration

1. When you create the verification scenario, set Integration Method to Web/H5. This value applies only to the web and H5 path.

2. Client-side integration — On the web and H5 pages that require verification, integrate the CAPTCHA initialization code. For a code sample, see Web and H5 client-side integration for V3 architecture.

3. Server-side integration — On your business server, integrate the SDK and call the VerifyIntelligentCaptcha operation to validate the CaptchaVerifyParam value that the client sends. For instructions, see Server-side integration.

App integration

An app loads the same web and H5 pages that you integrate in Web and H5 integration, so the client-side and server-side integration is identical. The Integration Method value and the app-side deployment are specific to the app path.

1. When you create the verification scenario, set Integration Method to Webview+H5 (Supports apps and mini-programs).

2. Complete the client-side and server-side integration described in steps 2 and 3 of Web and H5 integration. Step 1 of that section does not apply to the app path: keep Integration Method set to the value in the preceding step.

3. Deploy the integrated business pages in your app:

   • Android app — Use the WebView component to enable and deploy the business pages that must be integrated with CAPTCHA V2.0. For instructions, see Android integration for V3 architecture.

   • iOS app — Use the WKWebView component to enable and deploy the business pages that must be integrated with CAPTCHA V2.0. For instructions, see iOS integration for V3 architecture.

WeChat mini program integration

1. When you create the verification scenario, set Integration Method to Webview+H5 (Supports apps and mini-programs) or WeChat Mini Program Native Plugin.

2. Integrate the CAPTCHA initialization code into the WeChat mini program pages that use the verification feature. For instructions, see Mini Program integration.

Verify the integration

Run the following four checks after you complete any of the three integration paths. Each check builds on the previous one, so run them in order.

Check 1: The business client initializes the CAPTCHA

After the integration configuration is complete, open the browser console on the page into which the CAPTCHA is integrated and view the Network information. Client-side integration is successful if all of the following items exist:

• The initialization request.

• CAPTCHA-related information in the Preview of the initialization request, with Success set to true.

• The CAPTCHA resources.

The following example shows the response of an initialization request in which Success is true:

{
    "CaptchaType": "TRACELESS",
    "CertifyId": "3c6a84ac-xxx-xxx-xxx-xxx",
    "Code": "Success",
    "Message": "success",
    "StaticPath": "1.0.0/80c3280184eb1b98210a",
    "Success": true
}

Check 2: The business client verification succeeds

After a verification request is sent, open the browser console on the page into which the CAPTCHA is integrated and view the Network information. The verification is successful if VerifyResult is true.

The response of the client verification request also carries certifyId and securityToken, which distinguishes it from the server-side response in Check 3:

{
  "Code": "Success",
  "HttpStatusCode": 200,
  "Message": "success",
  "RequestId": "Exxxx...xxxx3",
  "Result": {
    "VerifyCode": "T001",
    "VerifyResult": true,
    "certifyId": "8JkVwuU1a2",
    "securityToken": "6o..."
  },
  "Success": true
}

Check 3: The business server integration succeeds

After client-side integration succeeds, the client sends the verification parameter CaptchaVerifyParam to the business server over the business API. The business server then calls the VerifyIntelligentCaptcha operation of the CAPTCHA server, which returns the verification result.

View the verification result in the response of the VerifyIntelligentCaptcha operation. Server-side integration is successful if VerifyResult is true.

{
    "RequestId": "C******-B***-4***-A***-5*******1",
    "Message": "success",
    "HttpStatusCode": 200,
    "Code": "Success",
    "Success": true,
    "Result": {
        "VerifyCode": "T001",
        "VerifyResult": true
    }
}

Check 4: The CAPTCHA works as expected for users

After server-side integration succeeds, the business result and the CAPTCHA result are returned to the client, and the client processes the business logic based on the returned results. Complete the CAPTCHA on the client to test the verification effect:

• Slider, jigsaw, click-to-pass, and image restore — The verification is successful if Verification Passed is displayed after you complete the verification as prompted.

• No-CAPTCHA verification — The verification is successful if the business interaction succeeds. In a logon scenario, for example, the verification is successful if Logon Successful is displayed after you enter your username and password and log on.

Slider, jigsaw, click-to-pass, and image restore

The following sequence diagram shows the verification flow for slider, jigsaw, click-to-pass, and image restore verification.

The diagram describes the following sequence:

1. A user initializes the CAPTCHA on the business client. The business client requests the JS resources of the CAPTCHA, such as images or challenges, from the CAPTCHA server.

2. The CAPTCHA server dynamically returns the relevant JS resources. The business client loads the resources and renders the CAPTCHA.

3. The user completes the CAPTCHA interaction on the business client, such as a slider, jigsaw, or image restore challenge. The JS automatically sends an answer verification request. The CAPTCHA server verifies whether the answer is correct and whether the request comes from a bot.

4. If the verification passes, the CAPTCHA server calls the success callback function and returns CaptchaVerifyParam. If the verification fails, the CAPTCHA is automatically refreshed and the user verifies again.

5. The business client sends a request that carries the business parameters and CaptchaVerifyParam to the business server for parameter validation.

6. The business server calls the VerifyIntelligentCaptcha operation of the CAPTCHA server to validate the CaptchaVerifyParam parameter.

7. The CAPTCHA server verifies whether the parameter is correct and whether the request comes from a bot, and then returns the verification result.

8. The business server processes the business logic based on the verification result, and then returns the verification result and the business result to the client web page.

No-CAPTCHA verification

The following sequence diagram shows the verification flow for no-CAPTCHA verification, including the secondary verification branch.

The diagram describes the following sequence:

1. A user initializes the CAPTCHA on the business client. The business client requests the JS resources of the CAPTCHA, such as images or challenges, from the CAPTCHA server.

2. The CAPTCHA server dynamically returns the relevant JS resources.

3. The first time the user clicks the trigger button on the business client to initiate verification, the CAPTCHA server verifies whether the user is a trusted user.

4. The CAPTCHA server returns the verification result to the business client:

   • If the user poses no risk, the first verification passes. The success callback function is called to return CaptchaVerifyParam for the subsequent business signature verification.

   • If the user poses a risk, the first verification is considered suspicious and a secondary verification is performed.

5. For a secondary verification, the business client loads the JS resources and renders the CAPTCHA. After the user completes the CAPTCHA interaction on the business client, such as a slider, jigsaw, or image restore challenge, the JS automatically sends an answer verification request. The CAPTCHA server verifies whether the answer is correct and whether the request comes from a bot.

6. If the secondary verification passes, the success callback function is called to return CaptchaVerifyParam for the subsequent business signature verification. If the secondary verification fails, the business client automatically refreshes the CAPTCHA and the user verifies again.

7. The business client sends a request that carries the business parameters and CaptchaVerifyParam to the business server for parameter validation.

8. The business server calls the VerifyIntelligentCaptcha operation of the CAPTCHA server to validate the CaptchaVerifyParam parameter.

9. The CAPTCHA server verifies whether the parameter is correct and whether the request comes from a bot, and then returns the verification result.

10. The business server processes the business logic based on the verification result, and then returns the verification result and the business result to the client web page.