Client integration and troubleshooting FAQ - Captcha

Integration patterns

How do I use multiple captchas on a single page?

Two approaches work:

Popup mode with a shared instance. Set the button element in initAliyunCaptcha to a hidden element. Bind a click event to the element that triggers the captcha and programmatically click the hidden button in that handler. This opens the captcha pop-up window and lets the entire page share one captcha instance.
Component encapsulation. Wrap the captcha as a reusable component and pass initialization parameters as props. After verification completes, remove the component from the DOM. For details, see Client V3 architecture demo download and Client V2 architecture demo download.

How do I integrate CAPTCHA for sending SMS verification codes?

Download the demo project for your architecture version:

How do I run custom logic before showing the captcha?

For example, to validate a phone number format before triggering a puzzle captcha:

Set the button parameter to a hidden element during initialization. The button parameter is required even when hidden. See Can I omit the button parameter? for details.
Run your validation logic.
If validation passes, call captcha.show() to display the captcha.

How do I trigger the captcha from JavaScript?

Call the show method on the captcha instance:

captcha.show();

Note

The show method is not supported for initial verification in traceless mode because the graphic captcha does not render. Do not trigger the captcha by simulating a click. Simulated clicks can be detected as automated tools in some scenarios, which leads to blocking.

Can I omit the button parameter when using the show method?

No. The button parameter is required. If your business does not have a visible button, use a hidden element. Omitting button causes captcha errors in some scenarios, such as in traceless mode.

V2 and V3 architecture

What instance methods are available in V2?

Call these methods on the captcha instance. None of these methods are supported for initial verification in traceless mode.

Method	Description	Example
`show`	Shows the captcha element or overlay.	`captcha.show()`
`hide`	Hides the captcha element or overlay.	`captcha.hide()`
`refresh`	Refreshes the captcha. Not supported in traceless mode.	`captcha.refresh()`
`destroyCaptcha`	Destroys the captcha instance and its elements.	`captcha.destroyCaptcha()`

Why does captchaVerifyCallback return results but the captcha does not respond? (V2 only)

This happens for one of two reasons:

1. The return statement is inside a nested callback.

If return is inside an ajax success callback but the outer captchaVerifyCallback function has no return, the CAPTCHA SDK cannot get the verification result. This blocks the verification flow.

Fix: Wrap the return value in a Promise and resolve it inside 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. The immediate parameter is missing in embedded mode.

In embedded mode, to send the request right after the user completes the slide or image selection, add immediate: true to the initialization method.

How do I refresh the captcha for re-verification in V3?

After a successful verification, the captcha lifecycle ends. To re-verify, call the initialization method again. For details, see the success callback function description in Web and H5 client V3 architecture integration.

Traceless mode

Does traceless mode work in an app with WebView and H5?

It depends on the WebView content. This applies to both V2 and V3 architecture:

WebView with business operations and a physical button that triggers verification: Yes, traceless verification works.
WebView with only captcha verification and no business operations: No. Traceless mode blocks all attempts. Select another captcha type instead, such as slider, one-click verification, puzzle captcha, or image restoration.

Why does the captcha not render even though the initialization request succeeds?

If no error appears in the browser developer tools console and the initialization request succeeded, check the CaptchaType field in the response. If it is set to TRACELESS, the captcha is in traceless mode. In traceless mode, the graphic captcha does not render on initial verification. This is expected behavior.

Error troubleshooting

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

The element or button element was not found. These elements must exist in the DOM before initialization. Pass the correct element ID in the initialization parameters.

Why does slideStyle not affect the puzzle captcha?

The slideStyle parameter affects only slider captchas, not puzzle captchas. Puzzle captcha dimensions are fixed. Modifying the image or slider length or width on the frontend causes verification to fail.

The captcha is not rendering. What should I check?

Two possible causes:

The initialization request to https://prefix.captcha-open.aliyuncs.com failed. This can happen due to network issues or a timeout. Check the browser developer tools console for errors. If the return value contains Forbidden.AccountAccessDenied, the failure is likely caused by an abnormal Alibaba Cloud account status or an overdue payment.
The initialization request succeeded but CaptchaType is TRACELESS. Traceless mode is active. The graphic captcha does not render on initial verification. See Why does the captcha not render even though the initialization request succeeds? for details.

The developer tools console shows "Console was cleared" and logs disappear. How do I keep the logs?

Clearing the console is a security action performed by CAPTCHA. It does not affect functionality. To retain logs during development, select the Preserve log option in the Console settings.

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

This is the default disaster recovery mechanism in CAPTCHA 2.0. If the initialization call fails, the success callback fires automatically. This skips the verification step when the product API is unavailable and prevents business operations from being blocked.

Platform integration

How do I send a verification request from an app client? (V2 only)

In captchaVerifyCallback, pass captchaVerifyParam to the app client through a platform-specific bridge:

Android: Call a custom Java interface such as testJsInterface.
iOS: Use a method that implements the WKScriptMessageHandler protocol for interaction between JavaScript and WKWebView.

After passing the parameter, close the H5 captcha window and initiate the verification request from the app client. When the app receives the verification result, it displays whether verification succeeded. If verification fails, the H5 window reappears for another attempt.

Note

Traceless mode is not supported in this scenario. The captcha is re-initialized for each verification, so a new lifecycle starts every time. Every attempt becomes a traceless verification. Even if a traceless verification fails, the next attempt does not trigger secondary verification, which weakens protection.

The WeChat mini program code package is too large. How do I reduce the size?

The plugin code uses a complex obfuscation mechanism for security, which increases its size. Use the subpackaging feature to place the pages that use the captcha into a subpackage.

For details, see:

Captcha resources fail to load during web client integration. What should I do?

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

API domain names

cloudauth-device.aliyuncs.com
cn-shanghai.device.saf.aliyuncs.com
cloudauth-device.ap-southeast-1.aliyuncs.com
ap-southeast-1.device.saf.aliyuncs.com
ap-southeast-1-ga.device.saf.aliyuncs.com
cloudauth-device-dualstack.cn-shanghai.aliyuncs.com
cloudauth-device-dualstack.ap-southeast-1.aliyuncs.com
****.captcha-open-southeast.aliyuncs.com
****.captcha-open-southeast-b.aliyuncs.com
****.captcha-open.aliyuncs.com
****.captcha-open-b.aliyuncs.com
****.captcha-open-dual.aliyuncs.com
****.captcha-open-dual-b.aliyuncs.com
****.captcha-open-southeast-dual.aliyuncs.com
****.captcha-open-southeast-dual-b.aliyuncs.com

Note

**** is a customer identifier.

Resource domain names

g.alicdn.com
o.alicdn.com
static-captcha.aliyuncs.com
static-captcha-sgp.aliyuncs.com