Captcha:Client Integration FAQ

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

• Method 1: Use the popup mode. Set the button element passed to the initAliyunCaptcha method as a hidden element, and then bind the relevant event (typically a click event) to the element where you want to trigger the captcha. In the event callback function, use JavaScript to trigger the click event on the button element to display the captcha popup. The entire page shares a single captcha instance.

• Method 2: Encapsulate the captcha as a component and use it wherever needed. Pass the initialization parameters as props. After the verification process is complete, unmount the captcha component (remove it from the DOM). For more information, see Web and H5 client V3 integration and Client V2 architecture demos.

Q2: How do I integrate the captcha for SMS verification scenarios?

• For details, see the V2 Architecture SMS Sending Scenario Demo (React).

• For details, see the V3 Architecture SMS Sending Scenario Demo (React).

Q3: How do I manually refresh or destroy the captcha, or manually show or close the captcha popup in the V2 client architecture?

Call the corresponding methods on the captcha instance. Note that the following methods are not supported during the first verification in traceless mode.

Q4: How do I make verification requests from the APP side for APP integration?

You can call a custom Java API testJsInterface (Android) or use the WkScriptMessageHandler protocol to implement JavaScript-to-WKWebView interaction (iOS) within the captchaVerifyCallback. This passes the captchaVerifyParam to the APP side. Then, close the captcha H5 window and initiate the verification request. After obtaining the verification result, the APP side can display a message indicating whether the verification passed. If it fails, display the H5 window again for re-verification. In this scenario, traceless verification mode is not supported because each verification reinitializes the captcha (starting a new captcha lifecycle), meaning every attempt becomes a traceless verification. Even if the traceless verification fails, the next attempt will not enter the secondary verification mode, resulting in slightly weaker protection.

Q5: How do I handle custom business operations before triggering the captcha popup? (For example, the puzzle captcha should only appear after the phone number format is validated.)

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

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

The element or button cannot be found. Both elements must exist in the DOM. You need to pass the correct element ID in the initialization parameters.

Q7: Why does the slider in the puzzle captcha not take effect after setting the slideStyle parameter?

The slideStyle parameter only applies to the slider captcha and does not affect the puzzle captcha. The solution for the puzzle captcha is fixed. You cannot modify the width or height of the image or slider on the frontend. Doing so may cause verification errors.

Q8: The captchaVerifyCallback returns the verification result, but why is the captcha not responding?

Possible causes include:

1. The return statement is declared inside a callback function such as the AJAX success callback, while the outer captchaVerifyCallback does not return anything. As a result, the captcha SDK cannot obtain the verification result, causing the verification flow to be blocked. To fix this, wrap the return value in a promise and resolve the result within 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. For embedded mode, if you need to immediately send a request after completing a slider swipe or image selection, add the immediate: true parameter to the initialization method.

Q9: I followed the demo code for integration, but why is the captcha not rendering?

Possible causes include:

1. Initialization request error:
   Check the browser developer tools console for any network error messages. Initialization request failures (to https://****.captcha-open.aliyuncs.com, where **** is the customer identity identifier) are typically caused by:

   • Network issues: The request fails or times out due to network instability.

   • Account issues: If the error code Forbidden.AccountAccessDenied is returned, the Alibaba Cloud account may be abnormal or have an outstanding balance.

2. Traceless verification mode:
   If the console shows no errors and the initialization request succeeds, check the CaptchaType field in the return value. If the value is TRACELESS, the current mode is traceless verification. In this mode, the graphical captcha is not rendered during the first initialization.

Q10: The upload code for the WeChat mini-program integration indicates that the code package is too large. How do I resolve this?

For security reasons, the plugin code uses a complex obfuscation mechanism, resulting in a large code size. You can resolve this by using the subpackage feature of WeChat mini-programs, which isolates the page that uses the captcha into a separate subpackage. For reference, see Native WeChat Subpackages, Taro WeChat Mini-Program Independent Subpackage, and Importing Plugin Code Packages in uni-app Subpackages.

Q11: What should I do if the web captcha fails to load resources during integration?

Check whether your system has domain filtering or URL filtering enabled. These features can cause failures when accessing important captcha resources or APIs. If enabled, add the following domains to the access whitelist:

Q12: What should I do if the developer tools console log is cleared with "Console was cleared" during captcha integration?

Clearing the developer tools console log is a security data collection action by the captcha and does not affect normal functionality. During development, you can enable "Preserve log" in the console settings to retain logs. In the Chrome DevTools Console panel, open the settings area and check the Preserve log checkbox to prevent logs from being cleared during page navigation.

Q13: Can I use the traceless mode when integrating the captcha via Webview + H5 within an app?

When integrating the captcha via Webview + H5 within an app (V2 or V3 architecture):

• If the Webview contains business pages (with business operations) and the verification is triggered by an actual button within the Webview, you can use traceless verification.

• If the Webview does not contain any business operations and is only used for captcha verification, traceless mode will block all requests. Choose another interactive captcha type, such as slider, one-click, puzzle, or image restoration.

Q14: In actual business scenarios where JavaScript is used to directly trigger the captcha, how do I display the captcha?

You can use the show method of the captcha instance to display the captcha (note that the graphical captcha is not rendered during the first verification in traceless mode, and the show method is not supported). It is not recommended to simulate clicks to trigger the captcha, as this may be identified as an automated tool in certain scenarios and result in blocking.

Q15: When using the show method of the captcha instance to display the captcha, there is no physical button on the business page. Can I omit the button initialization parameter?

No. The button parameter is required in the integration documentation. It can be used as a hidden element. Omitting this parameter may cause captcha errors in certain scenarios (such as traceless mode).

Q16: After successful verification in the V3 architecture, how do I refresh the captcha for a new verification?

After a successful verification, the captcha lifecycle ends. If you need to verify again, you must call the initialization method to reinitialize the captcha. Refer to the description of the success callback function in the code example in Web and H5 Client V3 Architecture Integration.

Q17: Why does the success callback fire after the initAliyunCaptcha initialization times out?

In the default disaster recovery mechanism of Captcha 2.0, a success callback is fired after the initialization call fails. This allows the verification step to be skipped when product API exceptions occur, preventing business flow blockage.

Q18: Error in native WeChat mini program integration: The AliyunCaptchaPluginInterface.show() function call failed

Symptoms:

When you use Captcha 2.0 with a native WeChat mini program, the `AliyunCaptchaPluginInterface.show()` method may return an `o.Config.show is not a function` error.

Possible causes and solutions:

1. The Mini Program plug-in is not integrated correctly. To integrate the plug-in, see Step 1: Declare the plugin and import the component.

   1. For native Mini Programs, check the app.json file and the JSON files for each page.

   2. For uni-app projects, check the manifest.json file and the JSON files for each page.

2. The captcha logic is executed before the aliyun-captcha component is loaded. To load the component, see Step 2: Insert the component template.

   1. The aliyun-captcha element in the WXML file is the frontend captcha component. The frontend page and its JavaScript (JS) script load synchronously. An error occurs if the JS script is loaded and executed before the frontend element is loaded.

3. There is a version mismatch for the Mini Program plug-in. The official documentation provides sample code for V2 and V3. Ensure that you use the corresponding plug-in version.

   1. You can find the Mini Program plug-in version information under WeChat Developer Tools > Details > Basic Information > Plug-in Information.