Client UI and custom configuration
The CAPTCHA client renders a different challenge for each verification type, in either a pop-up or an embedded layout. Customize the size, style, language, and callbacks of the CAPTCHA component when you initialize the client.
Client UI and interaction
Each verification type asks the user to complete a different action. In all layouts, the webpage loads and renders the CAPTCHA, waits for user interaction, and then returns a verification result.
| Verification type | User interaction |
| Slider verification | The pop-up is titled Complete the human verification. Drag the slider to the far right. |
| One-click verification | Select the checkbox labeled Confirm you are not a robot. |
| Puzzle verification | Drag the slider to fit the puzzle piece into the correct gap in the image. |
| Image restoration | Drag the slider to place the object in the correct position based on the image's context. |
Pop-up interaction UI
The pop-up interaction UI behaves the same way for all verification types. A pop-up is triggered, which renders the CAPTCHA and waits for user interaction. If the verification fails, the CAPTCHA refreshes for another attempt. After a successful verification, the pop-up closes.
Embedded interaction UI
The embedded interaction UI differs by verification type and by architecture version.
| Verification type | Embedded V2 architecture | Embedded V3 architecture |
| Slider verification | The slider verification component is embedded in the login form, below the account and password input fields. The slider area displays the prompt Please press and hold the slider and drag it to the far right. After completing the verification, the user clicks Login to submit. | The embedded UI is the same as in the V2 architecture. |
| One-click verification | The login page contains the embedded verification area, which displays the Confirm you are not a robot checkbox and the Alibaba Cloud logo. The account and password input fields are above this area, and the Login button is below it. | The embedded UI is the same as in the V2 architecture. |
| Puzzle verification | The user follows the prompt Please drag the slider to complete the puzzle and drags the puzzle piece to the gap in the background image. | The component is embedded in the login form as a bar between the password field and the Login button, and displays the text Click to start verification and the Alibaba Cloud logo. When the user clicks the bar, a puzzle verification pop-up appears. |
| Image restoration | The component is embedded in the login form. After entering a username and password, the user drags the slider to restore the image and then clicks Login. | The webpage loads and renders the CAPTCHA button. When the user clicks the button, an image restoration verification pop-up appears. |
The following figure shows the frontend interaction flow of the V3 architecture, which applies to all verification types.
Custom configuration
Most client customizations are configured by passing parameters to the initAliyunCaptcha function during client initialization. Others require CSS overrides or a request to your account manager. The following table lists each configuration item and the verification types that it applies to.
| Configuration item | Verification types | Description |
| Adjust CAPTCHA width or height | Slider verification, One-click verification | To set the width and height of the slider CAPTCHA, pass the slideStyle:{ width:360, height:40 } parameter to the initAliyunCaptcha function. The dimensions are in px. For security reasons, the minimum width is 320 px. If you specify a value smaller than 320, the width defaults to 320 px. If the slider width exceeds the screen width on some mobile devices, you can use the overall scaling feature to resolve this issue. |
| Adjust CAPTCHA width or height | Puzzle verification, Image restoration | Not supported. Overriding CSS to change the style causes verification errors. |
| Set overall CAPTCHA scaling | All verification types | Pass the rem:0.5 parameter to initAliyunCaptcha to scale the entire CAPTCHA UI. You must specify a positive number. For example, a value of 0.5 halves the size, and a value of 2 doubles the size. This parameter is primarily intended for mobile browsers. For more information, see V3 architecture access for web and H5 clients. |
| Modify page elements such as CAPTCHA color and font size | All verification types | Override the CSS of the corresponding page element. For examples, see Modify page elements by overriding CSS. |
| Set a custom company logo | One-click verification | Use the captchaLogoImg parameter during client initialization to change the company logo displayed to the right of the trigger button. For more information, see captchaLogoImg parameter for V3 architecture and captchaLogoImg parameter for V2 architecture. |
| Set a custom company logo | Slider verification, Puzzle verification, Image restoration | Not applicable |
| Set a custom image background | Puzzle verification | Contact your account manager to have a custom image background configured. For the image requirements and the lead time, see Set a custom image background. |
| Set a custom image background | Image restoration | The images are part of the challenge library and cannot be customized. |
| Set a custom image background | Slider verification, One-click verification | Not applicable |
| Set a custom language | All verification types | Pass the language parameter to initAliyunCaptcha to set the text language of the CAPTCHA component. |
| Set custom text | All verification types | Pass the upLang: myLang parameter to initAliyunCaptcha and define myLang to customize the text of the CAPTCHA component. |
| Callback function when the CAPTCHA is closed | All verification types | Use the onClose function. This callback function is triggered when the CAPTCHA pop-up is closed. |
| Callback function for frontend loading failures | All verification types | Use the onError function. This callback function is triggered when the CAPTCHA initialization API request or the loading of CAPTCHA resources fails or times out. |
Modify page elements by overriding CSS
Override CSS to modify page elements such as the CAPTCHA color and font size. This method applies to all verification types.
Example 1: When verification fails, an error code such as error: or9o8oyhlL appears in the input box, and the red prompt Verification failed. Refresh and try again. appears on the page. To hide the error code, find the element with the ID aliyunCaptcha-sliding-errorCode and override its CSS with display: none !important;. You can also change the style of the error prompt by overriding the CSS of its corresponding element.
Example 2: To change the color of the slider, modify the element with the ID aliyunCaptcha-sliding-slider by overriding its CSS color properties.
#aliyunCaptcha-sliding-slider {
background: #4285f4 !important;
color: #fff !important;
}Set a custom image background
A custom image background is available for puzzle verification only. Contact your account manager 7 to 10 business days in advance to have the images configured.
Prepare images that meet the following requirements:
Image dimensions: 300 × 200 pixels.
Image size: Up to 50 KB.
Number of images: 15 at minimum. More than 130 images are recommended. The more images you use, the stronger the security.