Captcha:Client integration FAQ

Q1: How do I handle multiple captchas on a single page?

• Method 1: Use popup mode. Set the button element passed to the initAliyunCaptcha method to a hidden element. Then, bind an event, such as a click event, to the element that triggers the captcha. In the event callback function, use JavaScript to trigger a click on the hidden button element. This opens the captcha pop-up window and allows the entire page to share a single captcha instance.

• Method 2: Encapsulate the captcha as a component and use it where needed. You can pass initialization parameters as props. After the verification is complete, remove the captcha component from the DOM. For more information, see Client V3 architecture demo download and Client V2 architecture demo download.

Q2: How do I integrate Captcha for sending text message verification codes?

• For more information, see V2 architecture demo for sending text messages (React).

• For more information, see V3 architecture demo for sending text messages (React).

Q3: For the V2 client architecture, how do I manually refresh or destroy a captcha, or manually show or hide the captcha pop-up window?

You can call the corresponding method of the captcha instance. These methods are not supported for the initial verification in traceless mode.

Q4: For app integration, how do I send a verification request from the app client?

In captchaVerifyCallback, you can call a custom Java interface testJsInterface (for Android) or use a method that uses the WkScriptMessageHandler protocol for interaction between JavaScript and WKWebView (for iOS). Pass the captchaVerifyParam to the app client, then close the H5 captcha window and initiate the verification request. After the app client receives the verification result, it displays whether the verification was successful. If the verification fails, the H5 window reappears for another attempt. Traceless mode is not supported in this scenario. This is because the captcha is re-initialized for each verification, which starts a new lifecycle. As a result, every attempt is a traceless verification. Even if a traceless verification fails, the next attempt does not trigger secondary verification, which weakens the protection.

Q5: How do I perform custom business operations before triggering the captcha pop-up window? (For example, triggering a puzzle captcha only after phone number format validation passes.)

After the custom business operation passes validation, you can use the captcha.show instance method to display the captcha for verification. The button element can be set as a hidden element. You must pass the button parameter during initialization (see Q15).

Q6: How do I resolve the 'Uncaught TypeError: Cannot set properties of undefined (setting 'onclick')' error?

This error occurs because the element or button element was not found. These elements must exist in the DOM. You must pass the correct element ID in the initialization parameters.

Q7: I set the slideStyle parameter, but why doesn't it affect the slider in the puzzle captcha?

The `slideStyle` parameter affects only slider captchas and does not apply to puzzle captchas. The dimensions of a puzzle captcha are fixed. The frontend cannot modify the length or width of the image or slider. Modifying these dimensions will cause verification to fail.

Q8: The captchaVerifyCallback returns verification result information, but why doesn't the captcha respond?

This can occur for the following reasons:

1. The `return` statement is declared within a callback function, such as an `ajax` success callback, but the outer `captchaVerifyCallback` function does not have a `return` statement. As a result, the Captcha software development kit (SDK) cannot obtain the verification result, which blocks the verification flow. To resolve this issue, wrap the return value in a promise and resolve the result in the callback.

   Correct example

   async function captchaVerifyCallback(captchaVerifyParam) {
     return new Promise((resolve) => {
       $.ajax({
         Url: 'xxxx',
         data: 'xxxx',
         success: (result) => {
           resolve({
             captchaResult: true,
             bizResult: false,
           });
         },
       });
     });
   }

   Incorrect example

   async function captchaVerifyCallback(captchaVerifyParam) {
     $.ajax({
       Url: 'xxxx',
       data: 'xxxx',
       success: (result) => {
         return {
           captchaResult: true,
           bizResult: false,
         };
       },
     });
   }

2. In embedded mode, to send the request immediately after completing the slide or image selection, add the immediate: true parameter to the initialization method.

Q9: I followed the demo code for integration, but why isn't the captcha rendering?

This can occur for the following reasons:

• The initialization request to the https://prefix.captcha-open.aliyuncs.com API failed. This failure might be due to network issues or a timeout. If the return value contains Forbidden.AccountAccessDenied, the failure might be caused by an abnormal Alibaba Cloud account status or an overdue payment. In these cases, a network error message appears in the console of your browser's developer tools.

• If no error message appears in the console of your browser's developer tools and the initialization request was successful, the CaptchaType field in the return value might be set to TRACELESS. This indicates traceless mode, where the graphic captcha does not render on initial verification.

Q10: When integrating with a WeChat Mini Program, I get a message that the code package is too large. How do I solve this?

For security reasons, the plugin code uses a complex obfuscation mechanism that increases its size. You can resolve this issue using the subpackaging feature of WeChat Mini Programs. This involves placing the pages that use the captcha into a subpackage. For more information, see Using subpackages in native WeChat, Independent subpackaging for Taro WeChat Mini Programs, and Importing plugin code packages within subpackages in uni-app.

Q11: During web client integration, what should I do if captcha resources fail to load?

Check whether your system has domain or URL filtering enabled. These features can block access to essential captcha resources or APIs. If these features are enabled, add the following domain names to the whitelist.

Q12: During captcha integration, the message 'Console was cleared' appears and logs are cleared from the developer tools console. How do I fix this?

Clearing the developer tools log is a security action performed by Captcha and does not affect normal functionality. During development, you can select the Preserve log option in the Console settings to retain the logs.

Q13: Can I use traceless mode when integrating Captcha in an app using WebView and H5?

When integrating Captcha (V2 or V3 architecture) in an app using WebView and H5:

• If the WebView contains a business page with business operations, and the verification is triggered by a physical button within the WebView, you can use traceless verification.

• If the WebView has no business operations and contains only the captcha verification, traceless mode will block all attempts. In this case, you must select another interactive captcha type, such as slider, one-click verification, puzzle captcha, or image restoration.

Q14: In my business scenario, I need to trigger the captcha directly using JavaScript. How can I do this?

You can use the show method of the captcha instance to display the pop-up captcha. The `show` method is not supported for the initial verification in traceless mode because the graphic captcha does not render. Do not trigger the captcha by simulating a click. This action can be detected as an automated tool in some scenarios, which leads to blocking.

Q15: After using the captcha instance's show method to display the captcha, my business does not have a physical button. Can I omit the button initialization parameter?

No, you cannot. The button parameter is required in the integration document. You can use a hidden element for this parameter. If you omit this parameter, captcha errors may occur in some scenarios, such as in traceless mode.

Q16: In the V3 architecture, how do I refresh the captcha for re-verification after a successful verification?

After a verification is successful, the captcha lifecycle ends. To re-verify, you must call the initialization method again to re-initialize the captcha. For more information, see the description of the success callback function in the code examples in Web and H5 client V3 architecture integration.

Q17: Why is the success callback triggered after the initAliyunCaptcha initialization times out?

In the default disaster recovery mechanism of Captcha 2.0, the success callback is triggered if the initialization call fails. This allows the verification step to be skipped when the product API is abnormal and prevents business operations from being blocked.