Captcha:FAQ

Service FAQ

Q1: What is the lifecycle of a CAPTCHA?

The following figure shows the lifecycle of a CAPTCHA.

During the entire process, you need to initialize a CAPTCHA only once. You do not need to call the initAliyunCaptcha method multiple times. Captcha 2.0 does not allow you to register multiple CAPTCHA instances on a single page. If you call the initAliyunCaptcha method multiple times, elements are repeatedly added and duplicate events are registered. This results in verification errors.

If multiple verification requests are sent in a verification process, the initAliyunCaptcha method may be called multiple times. In this case, you must check whether jitter prevention is configured for the button element that triggers the call of the initAliyunCaptcha method.

Q2: How do I call Captcha 2.0 in multiple places on the same page?

• Method 1: Use a pop-up CAPTCHA. Configure the button element that triggers the call of the initAliyunCaptcha method as a hidden element. Bind the related event to the element that needs to trigger a CAPTCHA. In most cases, a click event is used. In the event callback function, use the JavaScript code to trigger the click event of the button element to display a pop-up CAPTCHA. This way, the same CAPTCHA instance is shared on the entire page.

• Method 2: Encapsulate a CAPTCHA as a component and use the component based on your business requirements. You can specify initialization parameters of the CAPTCHA by using props. After the verification process is complete, you must uninstall the component by removing the component from the Document Object Model (DOM). For more information, see the source code of client integration demos.

Q3: How do I integrate Captcha 2.0 in the scenario in which a mobile phone is used to obtain a verification code?

For more information, see the source code of react-sms-demo.

Q4: How do I manually refresh or destroy a CAPTCHA or manually display or close a pop-up CAPTCHA?

Call the methods of the CAPTCHA instance. The following table describes the methods that are not supported for the initial verification of an invisible CAPTCHA.

Q5: How do I verify a request in an application after Captcha 2.0 is integrated into the application?

You can pass the captchaVerifyParam parameter to the application in the captchaVerifyCallback method. To do so, you can call the testJsInterface Java method for an Android application or initiate interaction between JavaScript and WKWebView by using the WkScriptMessageHandler protocol for an iOS application. Then, close the HTML5 CAPTCHA window and initiate a verification request. After the verification result is obtained, the result is automatically displayed in the application. If the verification fails, display the HTML5 CAPTCHA window for another verification. In this scenario, we recommend that you do not use an invisible CAPTCHA. A CAPTCHA is initialized for each verification in a new verification cycle. As a result, an invisible CAPTCHA is initialized each time, and no additional CAPTCHA is triggered even if an invisible CAPTCHA is not passed. Therefore, the protection effect is mitigated.

Q6: How do I perform custom business processing before a pop-up CAPTCHA is triggered?

You can configure the button element to be passed to the initAliyunCaptcha method as a hidden element. Bind the related event to the element that needs to trigger a CAPTCHA. In most cases, a click event is used. In the event callback function, perform business processing, such as business parameter verification. Then, use the JavaScript code to trigger the click event of the button element.

Q7: How does an invisible CAPTCHA work?

The following figure shows the sequence diagram of an invisible CAPTCHA.

• If the value of the captchaResult parameter is false, an additional CAPTCHA is automatically triggered.

• If the value of the captchaResult parameter is true, the onBizResultCallback method is called to perform operations such as displaying a prompt or navigating users to another page.

Q8: What do I do if the "Uncaught TypeError: Cannot set properties of undefined (setting 'onclick')" error message appears?

The element or button element is not found. The two elements must exist in the DOM. You must specify valid element IDs in the initialization parameters.

Q9: Why does the slideStyle parameter fail to take effect for a puzzle CAPTCHA?

The slideStyle parameter takes effect only for slider CAPTCHAs. This parameter does not take effect for puzzle CAPTCHAs. The answer to a puzzle CAPTCHA is fixed. You cannot modify the length or width of the image or slider. Otherwise, the verification fails.

Q10: The verification result is returned in the captchaVerifyCallback method. However, the CAPTCHA stops responding. Why?

You may encounter this error due to the following reasons:

1. The return statement is declared in the success callback function of Asynchronous JavaScript And XML (AJAX). The outer captchaVerifyCallback method cannot return the verification result to CAPTCHA 2.0 SDK. As a result, the verification process is blocked. In this case, you must encapsulate the return body into a promise and then resolve the result in the captchaVerifyCallback method.

   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, if you want to send a request immediately after the slider is dragged or the image is selected, you must add the immediate: true parameter to the initAliyunCaptcha method.

Q11: Why is the CAPTCHA not rendered after I integrate Captcha 2.0 into a business client?

You may encounter this error due to the following reasons:

• The initialization request failed. The URL of the initialization request is https://prefix.captcha-open.aliyuncs.com. The request may fail or time out due to network issues. If the Forbidden.AccountAccessDenied code is returned, the request may fail due to an Alibaba Cloud account exception or an overdue payment. In this case, an error message is displayed in the console of the browser developer tool.

• If no error message is displayed in the console of the browser developer tool and the initialization request is successful, the value of the CaptchaType parameter in the response may be TRACELESS. The value indicates an invisible CAPTCHA. In this case, the CAPTCHA is not rendered during the first initialization. For more information about the verification logic, see Q7: How does an invisible CAPTCHA work?

Q12: What do I do if a message indicating that the code package is excessively large appears when I integrate Captcha 2.0 into a WeChat mini program?

The code package is excessively large because the code uses obfuscation for security purposes. You can use the subpackage mechanism for WeChat mini programs to process the excessively large code package when you integrate Captcha 2.0 into a WeChat mini program. For more information, see Using Subpackage, WeChat mini program independent subpackage, and Import plugin code package in subpackage.

Q13: What do I do if the CAPTCHA resources fail to be loaded on a web client when I integrate Captcha 2.0 into the web client?

Check whether domain name filtering or website URL filtering is enabled for your system. If one of the preceding filtering mechanisms is enabled for your system, the access to important CAPTCHA resources or the call of CAPTCHA API operations fails. To resolve the issue, add the following domain names to your access whitelist.

Q14: Is there a callback function configured for the close button of a pop-up CAPTCHA? What do I do if I want custom operations to be triggered when a user clicks the close button of a pop-up CAPTCHA?

No callback function is configured for the close button of a pop-up CAPTCHA. If you want custom operations to be triggered when a user clicks the close button of a pop-up CAPTCHA, perform the following operations: In the callback function of the getInstance method, rewrite the click event of the aliyunCaptcha-btn-close or aliyunCaptcha-mask element to call the captcha.hide() instance method to hide or mask the CAPTCHA and perform custom operations.