Captcha integration methods-Captcha(Captcha)-阿里云帮助中心

Captcha is a captcha solution from Alibaba Group. Most users can complete the captcha with a single click. Captcha uses an advanced risk analysis engine to distinguish between human and machine access. It blocks machine-based threats and provides a secure and reliable business environment.

Frontend code integration

Initialize Captcha on the frontend web pages where you want to use the feature. The following code provides an example of frontend integration.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
<script src="https://g.alicdn.com/AWSC/AWSC/awsc.js"></script>
</head>
<body>
<div id="sc"></div>
<script>
    // Instantiate the ic object.
    AWSC.use("ic", function (state, module) {
        // Initialize.
        window.ic = module.init({
            // The application type identity. It works with the scenario identity (the scene field) to determine the business scenario and the backend policy model for Captcha. Find the appkey value on the Configuration Management tab in the Alibaba Cloud Captcha console. Enter the value correctly.
            appkey: "CF_APP_1",
            // The scenario identity. It works with the application type identity (the appkey field) to determine the business scenario and the backend policy model for Captcha. Find the scene value on the Configuration Management tab in the Alibaba Cloud Captcha console. Enter the value correctly.
            scene: "nvc_register",
            // The ID of the target element where Captcha will be rendered.
            renderTo: 'sc',
            // This callback parameter is triggered when the authentication succeeds. In this callback, record the session ID (sessionId), signature string (sig), and unique request token (token). Send these fields with the business request to your server for signature verification.
            success: function (data) {
                window.console && console.log(data.sessionId)
                window.console && console.log(data.sig)
                window.console && console.log(data.token)
            },
            // This callback parameter is triggered when the authentication fails.
            fail: function (failCode) {
                console.log(failCode)
            },
            // This callback parameter is triggered when the captcha fails to load.
            error: function (errorCode) {
                console.log(errorCode)
            }
        });
    })
</script>
</body>
</html>

Initialization

Import resources
To use the slide authentication feature on a web page, add the following code to your frontend page to import the required JS resource: <script src="https://g.alicdn.com/AWSC/AWSC/awsc.js"></script>.

Initialization code description

 // Instantiate the ic object.
    AWSC.use("ic", function (state, module) {
        var icOption = {} // The initialization parameter object for Captcha.
        // Initialization. Call module.init to initialize Captcha.
        window.ic = module.init(icOption);
    })

Note

After module.init completes initialization, it returns an instantiated ic object. In the example code, this object is stored in the window.ic variable.

Initialization parameter descriptions

The following initialization parameters are available when you instantiate the authentication component in the frontend code. You can adjust these parameters in the code as needed.

Parameter	Description	Required
appkey	The application type identity. It works with the scenario identity (the `scene` field) to determine the business scenario and the backend policy model for Captcha. Find the `appkey` field value on the Configuration Management tab in the Alibaba Cloud Captcha console. Enter the value correctly.	Yes
scene	The scenario identity. It works with the application type identity (the `appkey` field) to determine the business scenario and the backend policy model for Captcha. Find the `scene` value on the Configuration Management tab in the Alibaba Cloud Captcha console. Enter the value correctly.	Yes
renderTo	The ID of the target element where Captcha will be rendered.	Yes
width	The width of the Captcha component. The default value is 300 px. Set the width to at least 300 px.	No
language	The language of the authentication component. The default value is `cn` (Chinese).	No
upLang	Used to customize the text for secondary authentication. For more information about how to configure this, see Custom text.	No
height	The height of the Captcha component. The default value is 42 px. Set the height to at least 42 px.	No
default_txt	The text for the initial state of the Captcha component.	No
success_txt	The text for the success state of the Captcha component.	No
fail_txt	The text for the failed (blocked) state of the Captcha component.	No
scanning_txt	The text for the scanning state of the Captcha component.	No
test	A test field used to test different states of the captcha.	No
success	This callback function is triggered when the frontend Captcha authentication succeeds. In this callback, record the session ID (`sessionid`) and signature string (`sig`). Send these fields with the business request to your server for signature verification.	No
fail	This callback function is triggered when the Captcha authentication fails.	No
error	This callback function is triggered when an error occurs in Captcha.	No

Testing

After you integrate the frontend code into your web page, test it using the following methods before deployment.

Set the test parameter to reproduce different states

You can set the `test` field to different values that are provided by the Captcha service to test the effect of each state. Configure the `test` field in the frontend page initialization code to directly control the result (pass or block) that is returned by the Captcha service API.

Value of the test field	Simulated effect
module.TEST_PASS	Captcha passes.
module.TEST_BLOCK	Captcha fails and is blocked directly.
module.TEST_NC_PASS	Wakes up slide authentication, and the slide authentication passes.
module.TEST_NC_BLOCK	Wakes up slide authentication, and the slide authentication fails.

Note

The prefix module is the object returned by AWSC.use. In the example code, it is named module.
In the new version of the integration code, the token is generated automatically. You do not need to specify the token. If you do not delete the test configuration item before deployment or before you perform a full functional test, a token exception will occur. This may lead to an exception in one of the integration steps, such as a signature verification failure.

This way, you can directly observe the interaction, style, and flow of the captcha in each state.

Test code example:

AWSC.use("ic", function (state, module) {
  window.ic = module.init({
    ...
    ...
    // This configuration item is for testing. Use it only to test different captcha states. Delete it before going online. The Captcha test configuration item has four different values that correspond to different captcha states. For more information, see the parameter definition description in this document.
    test: module.TEST_PASS, // Test Captcha pass
    // test: module.TEST_BLOCK, // Test Captcha fail
    // test: module.TEST_NC_PASS, // Wake up slide authentication and pass
    // test: module.TEST_NC_BLOCK, // Wake up slide authentication and fail
    ...
    ...
  });
})

Before deployment, perform full functional and compatibility tests. During testing, note the following:
- During testing, make sure to use the appkey and scene values that are assigned to you in the Alibaba Cloud Captcha console.
- The authentication component supports Internet Explorer 9 and later. It does not support Internet Explorer 8 or earlier.
- During a full functional test, if the token that is obtained from a successful call contains CF_APP_1, check whether the test configuration item has been deleted. This prevents the full functional test from failing.

Working with the generated ic object

After module.init completes initialization, it returns an instantiated ic object. In the example code, this object is stored in the window.ic variable. The object provides several methods that you can use to perform further operations. You can call the methods using window.ic[methodName].

Method name	Parameter	Function
reset	None	Call this method at any time to reset Captcha to its initial state (waiting for interaction).