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

No-interaction Verification is a new Captcha solution from Alibaba Group. This component collects information and schedules downstream Captcha services to perform comprehensive human-machine detection.

After you integrate No-interaction Verification into your service, the component silently collects the required information. This process creates a zero-interruption experience for most users. For users who pose a risk, the component suggests invoking a downstream Captcha service based on the risk level. This action involves calling the appropriate Captcha service to perform an Alibaba Cloud Captcha check.

Frontend integration code example

On the web frontend page where you want to use No-interaction Verification, you must first initialize the service. Then, you can actively obtain the human-machine information string and send it to your business server. The business server queries the risk control server and returns the result to the client. The client then determines whether to pass, block, or trigger secondary authentication based on the risk level. The following code provides an example of frontend integration for No-interaction Verification.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <script src="https://g.alicdn.com/AWSC/AWSC/awsc.js"></script>
</head>
<body>
<form id="login-form">
    <input id="account" type="text" placeholder="Account" />
    <input id="password" type="password" placeholder="Password">
    <button type="button" id="register" >Register</button>
</form>
<div id="nc"></div>
<script>
    var btn = document.getElementById("register");
    // Instantiate nvc to initialize No-interaction Verification.
    AWSC.use("nvc", function (state, module) {
        // Initialize by calling module.init.
        window.nvc = module.init({
            // The application type identifier. Together with the scenario identifier (the scene field), it determines the business scenario for No-interaction Verification and the corresponding backend policy model. You can find the appkey value on the Configuration Management tab of the Alibaba Cloud Captcha console. Make sure to enter it correctly.
            appkey: "CF_APP_1",
            // The scenario identifier. Together with the application type identifier (the appkey field), it determines the business scenario for No-interaction Verification and the corresponding backend policy model. You can find the scene value on the Configuration Management tab of the Alibaba Cloud Captcha console. Make sure to enter it correctly.
            scene: "nvc_register",
            // On successful secondary authentication, this callback receives the human-machine information string. Send this string to your server for signature verification.
            success: function (data) {
               window.console && console.log(data)
            },
            // This callback is triggered when frontend secondary authentication fails.
            fail: function (failCode) {
               window.console && console.log(failCode)
             },
             // This callback is triggered when an exception occurs while loading the frontend secondary authentication.
             error: function (errorCode) {
               window.console && console.log(errorCode)
             }
        });
        // Bind the event.
        btn.onclick = onclick;
    });
    // Send the business request: Triggered on button click. Actively gets the human-machine information string and sends it to the business server.
    function onclick() {
        window.nvc.getNVCValAsync(function (nvcVal) {
            var s = document.createElement('script');
            // Get the human-machine information string.
            // Upload the value from the getNVCVal() function with your business request. The backend then requests the AnalyzeNvc API and returns 200, 400, 600, or 800.
            // Before you go live, you must change this server-side API to your own business server-side API.
            s.src = 'https://cf.aliyun.com/nvc/nvcAnalyze.jsonp?callback=yourRegisterRequest&a=' + nvcVal;
            document.body.append(s);
        });
    }
    // Handle the business return result: This is the callback function for the human-machine information string upload API. Control the state of No-interaction Verification based on the result from the business server.
    function yourRegisterRequest(json) {
        // The business server request callback controls whether secondary authentication is needed.
        if (json.result.code === 100 || json.result.code === 200) {
            // No-interaction Verification passed.
            alert("register success!")
        } else if (json.result.code === 800 || json.result.code === 900) {
            // No-interaction Verification failed. Block the request directly.
            alert("register failed!")
        } else if (json.result.code === 400) {
            // No-interaction Verification failed. Trigger secondary authentication.
            // Secondary CAPTCHA (slider CAPTCHA) configuration item settings. For more information, see the slider verification integration document.
            // The appkey, scene, and test values, and the success, fail, and error callbacks for secondary authentication are determined during nvc initialization. Do not pass them during secondary authentication.
            var ncoption = {
               // Declare the target ID where the slider verification will be rendered.
               renderTo: "nc",
            }
            // Invoke secondary authentication (slider CAPTCHA).
            window.nvc.getNC(ncoption);
        }
    }
</script>
</body>
</html>

Initialization

Import resources
To use No-interaction Verification on a web page, you can add the following code to your frontend page to import the required JavaScript (JS) resource. <script src="https://g.alicdn.com/AWSC/AWSC/awsc.js"></script>.

Initialization code description

AWSC.use("nvc", function (state, module) {
        var nvcOption = {} // nvc initialization parameter object
        // Initialize by calling module.init.
        window.nvc = module.init(nvcOption);
    });

Note

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

Initialization parameter description

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

Parameter	Description	Required
appkey	The application type identifier. Together with the scenario identifier (the `scene` field), it determines the business scenario for No-interaction Verification and the corresponding backend policy model. You can find the `appkey` field value on the Configuration Management tab of the Alibaba Cloud Captcha console. Make sure to enter it correctly.	Yes
scene	The scenario identifier. Together with the application type identifier (the `appkey` field), it determines the business scenario for No-interaction Verification and the corresponding backend policy model. You can find the `scene` value on the Configuration Management tab of the Alibaba Cloud Captcha console. Make sure to enter it correctly.	Yes
test	A test field used to test different states of the Captcha.	No
success	You can obtain the human-machine information string after a successful secondary authentication.	No
fail	This callback is triggered when secondary authentication fails.	No
error	This callback is triggered when an error occurs during secondary authentication.	No

Send a business request

After No-interaction Verification is initialized, you can actively call the getNVCVal method of the nvc object to obtain the human-machine information string. Pass this string with your business request to your business server. Then, you can initiate a risk query request from your business server to the risk control server. For more information, see the server-side code integration document.

function onclick() {
        // After the bound event is triggered, actively call the getNVCVal method.
        window.nvc.getNVCValAsync(function (nvcVal) {
            var s = document.createElement('script');
            // Upload the value from the getNVCVal() function with your business request. The backend then requests the AnalyzeNvc API and returns 200, 400, 600, or 800.
            // Before you go live, you must change this server-side API to your own business server-side API.
            s.src = 'https://cf.aliyun.com/nvc/nvcAnalyze.jsonp?callback=yourRegisterRequest&a=' + nvcVal;
            document.body.append(s);
        });
    }

Note

You must replace the default API https://cf.aliyun.com/nvc/nvcAnalyze.jsonp in the example with your own business request API. The default API is an online demo test API and does not provide any actual attack and defense capabilities.

Handle the business return result

After you receive the risk query result, you can return it directly to the client. The client can then pass, block, or invoke secondary authentication based on the risk level. To invoke secondary authentication, you can call the getNC method of the nvc object on a specified div. If your business server has its own risk control policies, such as whitelists and blacklists, you can combine the results from your policies and the Alibaba Cloud Captcha API to decide on the final risk handling method for the client.

function yourRegisterRequest(json) {
        // Based on the business server's response, control whether to pass, block, or trigger secondary authentication for No-interaction Verification.
        if (json.result.code === 100 || json.result.code === 200) {
            // No-interaction Verification passed.
            alert("register success!")
        } else if (json.result.code === 800 || json.result.code === 900) {
            // No-interaction Verification failed. Block the request directly.
            alert("register failed!")
        } else if (json.result.code === 400) {
            // No-interaction Verification failed. Trigger secondary authentication.
            var ncoption = {} // ncoption is the initialization parameter object for secondary authentication. For details, see the slider verification initialization parameters.
            // Invoke secondary authentication (slider CAPTCHA).
            window.nvc.getNC(ncoption);
        }
    }

Note

For details about the initialization parameters for secondary authentication, see the list of slider CAPTCHA initialization parameters. The appkey, scene, and test values, and the success, fail, and error callbacks are determined during nvc initialization. Do not pass them during secondary authentication.

Testing

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

Simulate different verification states using the test parameter

You can test the effect of different states by setting the test field to different values provided by the No-interaction Verification service. You can configure the test field in the frontend page initialization code to directly control the return result (pass or block) of the No-interaction Verification service API. For example, when you use the https://cf.aliyun.com/nvc/nvcAnalyze.jsonp server-side API provided in the code example for testing, the relationship between the test field value and the result returned by the service API is shown in the following table:

`test` field value	Simulated effect
module.TEST_PASS	No-interaction Verification passes.
module.TEST_BLOCK	No-interaction Verification fails and is blocked directly.
module.TEST_NC_PASS	Invokes slider verification, and the verification passes.
module.TEST_NC_BLOCK	Invokes slider verification, and the verification fails.

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

Note

The prefix module is the object returned by AWSC.use. In the example code, it is named module.
Before you go live, you must delete the test configuration item from the integration code to avoid security issues. 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 you go live or perform complete functional testing, a token exception may occur. This may lead to an exception in one of the integration steps, such as a signature verification failure.

Test code example:

AWSC.use("nvc", function (state, module) {
    window.nvc = module.init({
       ...
       ...
       // This configuration item is for testing only. Use it only to test different Captcha states. Delete it before you go live. The No-interaction Verification test configuration item has four different values corresponding to different Captcha states. For details, see the parameter definition description in this document.
       test: module.TEST_PASS, // Test No-interaction Verification pass
       // test: module.NVC.TEST_BLOCK, // Test No-interaction Verification fail
       // test: module.TEST_NC_PASS, // Invoke secondary authentication (slider verification), and the verification passes
       // test: module.TEST_NC_BLOCK, // Invoke secondary authentication (slider verification), and the verification fails
       ...
       ...    
    });
});

Perform functional and compatibility testing.
Before you go live, you must perform complete functional and compatibility testing. During testing, note the following:
- In the frontend code, you must replace the http://cf.aliyun.com/nvc/nvcAnalyze.jsonp server-side API provided in the code example with your own business API. Then, you must integrate Alibaba Cloud Captcha on the server-side according to the No-interaction Verification server-side code integration guide.
- During testing, make sure to use the appkey and scene values assigned to you in the Alibaba Cloud Captcha console.
- For Internet Explorer, the verification component supports Internet Explorer 9 and later versions. It does not support Internet Explorer 8 or earlier versions.
- 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 you go live or perform complete functional testing, a token exception may occur. This may lead to an exception in one of the integration steps, such as a signature verification failure.