Integrate with Web and H5 clients using the V3 architecture - Captcha

After you add a verification scenario in the console, you must integrate the Captcha initialization code into your Web or H5 page. This topic describes how to perform the integration.

Prerequisites

The Alibaba Cloud Captcha 2.0 service is activated.
A verification scenario has been created with the Integration Method set to Web/H5.

Method overview

Integrate your client with Captcha 2.0 by following these three steps:

Add the AliyunCaptchaConfig global variable.
Dynamically load the Captcha JS file.
Call the initializer method to initialize Captcha.

Note

If your service uses the V2 architecture, see Integrate with Web and H5 clients using the V2 architecture.
The V3 architecture is not supported for WeChat mini programs.

Procedure

Step 1: Add the AliyunCaptchaConfig global variable

Before you load the Alibaba Cloud Captcha JS script, or at the beginning of the HTML <head> tag, add a script that defines a global variable named AliyunCaptchaConfig. This variable must contain the region and prefix parameters.

<script>
  window.AliyunCaptchaConfig = {
    // Required. The region where the Captcha instance resides. Valid values: cn (the Chinese mainland) and sgp (Singapore).
    region: "cn",
    // Required. The identity prefix. After you activate Captcha 2.0, you can obtain the identity prefix from the instance information card on the Overview page in the console.
    prefix: "******",
  };
</script>

Important

You can find the identity prefix under Overview > Cumulative Activation Time > Identity Prefix, as shown in the following figure:

Step 2: Dynamically import the Captcha JS file

Your web page must dynamically load the Captcha JS file. When verification is required, call the Captcha service to perform the verification.

Note

You must dynamically load the Captcha JS file. If you bypass dynamic loading, such as by downloading the JS code for local deployment, the Captcha service cannot be updated. This can compromise security and cause incorrect blocking or compatibility issues.

<script
  type="text/javascript"
  src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
></script>

Step 3: Call the initializer method to initialize Captcha.

The initAliyunCaptcha initializer method should not be called repeatedly, except in specific scenarios, such as when initialization parameters change. If the initialization fails, see Client-side initialization errors for troubleshooting information.

<script type="text/javascript">
  var captcha;
  // Parameters other than region and prefix
  window.initAliyunCaptcha({...});
</script>

Code example

Note

Load the Captcha JS file as early as possible to collect more complete environment and device information. The interval between loading the JS file and sending a verification request must be greater than 2 s.
To ensure faster loading of image resources, initialize Captcha as early as possible. The interval between initialization and sending a verification request must be greater than 2 s. This preloads Captcha resources and speeds up image loading.
In the client source code, reserve a page element for the Captcha service. The `element` and `button` parameters must point to this DOM element, such as <div id="captcha-element"></div> in the following example.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="data-spm" />
    <!--1. Before you import the Alibaba Cloud Captcha JS script, or at the beginning of the HTML head tag, add a script to save a global variable named AliyunCaptchaConfig. This variable must contain the region and prefix parameters.-->
    <script>
      window.AliyunCaptchaConfig = {
        // Required. The region where the Captcha instance resides. Valid values: cn (the Chinese mainland) and sgp (Singapore).
        region: "cn",
        // Required. The identity prefix. After you activate Captcha 2.0, you can obtain the identity prefix from the instance information card on the Overview page in the console.
        prefix: "xxxxxx",
      };
    </script>
    <!--2. Integrate the main JS file.-->
    <script
      type="text/javascript"
      src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
    ></script>
  </head>

  <body>
    <div id="captcha-element"></div>
    <!--The reserved Captcha element, used to configure the element parameter in the initializer function.-->
    <button id="button" class="btn">Log on</button>
    <!--In popup mode, this element triggers the Captcha dialog box.-->
    <!--3. Create a <script> tag to call the initAliyunCaptcha initializer function.-->
    <script type="text/javascript">
      var captcha;
      // In popup mode, these are the parameters other than region and prefix.
      window.initAliyunCaptcha({
        // The scenario ID. After you create a verification scenario, you can obtain its ID from the list of verification scenarios.
        SceneId: "******",
        // The Captcha mode. `popup` indicates popup mode, and `embed` indicates embedded mode. You do not need to modify this.
        mode: "popup",
        // The reserved element on the page for rendering Captcha. This must be consistent with the reserved page element in the source code.
        element: "#captcha-element",
        // The element that triggers the Captcha dialog box or the no-captcha verification.
        button: "#button",
        // The callback function for successful Captcha verification.
        success: function (captchaVerifyParam) {
          // The input parameter is captchaVerifyParam for signature verification.
          // 1. Send a request to the backend to verify the captchaVerifyParam.
          // 2. Process the service based on the verification result.
          // 3. If your service requires re-verification, call the initAliyunCaptcha initializer method to re-initialize Captcha.
        },
        // The callback function for failed Captcha verification.
        fail: function (result) {
          // The input parameter contains the failure information.
          // Within the normal validity period, no action is required. Captcha automatically refreshes for re-verification.
          console.error(result);
        },
        // The callback function to bind the Captcha instance. This callback is invoked after Captcha is successfully initialized.
        getInstance: function (instance) {
          captcha = instance;
        },
        // The style of the trigger box for slider and point-and-click verification. You can customize the width and height in pixels (px).
        slideStyle: {
          width: 360,
          height: 40,
        },
        // ...For other parameters, see the initAliyunCaptcha parameter descriptions.
      });
    </script>
  </body>
</html>

Parameter descriptions

AliyunCaptchaConfig parameters

Parameter

Type

Required

Default value

Description

region

String

Yes

The region where the Captcha instance resides. Valid values:

cn: the Chinese mainland.
sgp: Singapore.

Important

If the client region is `cn`, call the endpoint for the Chinese mainland on the server. If the region is `sgp`, call the endpoint for Singapore.
The product has control planes in the Chinese mainland (China (Shanghai)) and Singapore. Based on the call parameters you configure, the client collects and sends behavioral data and device data to the corresponding center for processing. This is mainly used for security authentication.

prefix

String

Yes

None

The identity prefix for Captcha. After you activate Captcha 2.0, you can obtain this value from the upper-right corner of the Overview page in the console.

initAliyunCaptcha parameters

Call the Captcha initializer method as early as possible after the page loads.

Parameter	Type	Required	Default value	Description
SceneId	String	Yes	None	The scenario ID for Captcha. You can obtain this value after you create a verification scenario.
mode	String	Yes	None	The Captcha mode. Options: popup: popup mode. embed: embedded mode. Important No-captcha verification does not support embedded mode. Use popup mode for integration.
element	String	Yes	None	The reserved element on the page for rendering Captcha. This must be consistent with the reserved page element in the source code.
button	String	Yes	None	The element that triggers the Captcha dialog box or no-captcha verification. When clicked, it displays the Captcha or triggers no-captcha verification. The value must be the same as the `button` parameter value in the client body.
success	Function	Yes	None	The callback function for successful Captcha verification. This function passes the verification parameters. In this callback function, you can obtain the `CaptchaVerifyParam` and send a request to your server to validate the `CaptchaVerifyParam`.
fail	Function	No	None	The callback function for failed Captcha verification. This function exposes the error code for the failure.
getInstance	Function	Yes	getInstance	The callback function to bind the Captcha instance. This callback is invoked after Captcha is successfully initialized. The syntax is fixed: `function getInstance(instance) { captcha = instance; }`
slideStyle	Object	No	{ width: 360, height: 40 }	The style of the trigger box for slider and point-and-click verification. You can customize the width and height in pixels (px). This parameter is compatible with historical parameter names. Important Because Captcha needs to collect enough information from the sliding action for its policy model to make a judgment, set the minimum slider width (the width value) to 320 px. If the width value is less than 320 px, the system uses 320 px. This parameter does not apply to puzzle or image restoration verification. If you use puzzle Captcha, do not override the CSS to force style changes. The image size and verification answer for puzzle Captcha are preset and fixed. Modifying the style will cause verification to fail.
language	String	No	cn	The language types supported by Captcha 2.0.
timeout	Number	No	5000	The timeout period for a single Captcha initialization request, in milliseconds (ms).
rem	Number	No	1	Scales the entire Captcha UI. Enter a positive number. For example, 0.5 halves the size, and 2 doubles the size. Note The rem parameter is mainly for mobile browsers.
onError	Function	No	None	The error callback function for failures or timeouts in Captcha initialization API requests and resource loading.
onClose	Function	No	None	The callback function that is triggered when the Captcha dialog box is closed.
captchaLogoImg	String	No	None	The parameter to replace the company logo to the right of the trigger button for point-and-click, puzzle, or image restoration verification in embedded mode. The value can be an image URL or base64-encoded data.
dualStack	Boolean	No	false	Specifies whether to enable dual-stack for the initialization request domain name and the verification request domain name. Valid values: false: Only IPv4 is supported. true: Both IPv4 and IPv6 are supported.
showErrorTip	Boolean	No	true	Specifies whether to display an error message for access exceptions when the network quality is poor.
delayBeforeSuccess	Boolean	No	true	Specifies whether to delay the success callback function by 1s after a successful verification. The default value is true.

rem parameter code example

const customWidth = 360;
function initCaptcha(rem) {
  window.initAliyunCaptcha({
    SceneId: "xxxxxx",
    mode: "popup",
    element: "#captcha-element",
    button: "#captcha-button",
    success: success,
    fail: fail,
    getInstance: getInstance,
    slideStyle: {
      width: customWidth,
      height: 40,
    },
    language: "cn",
    rem: rem,
  });
}

const pageWidth = window.innerWidth;
if (pageWidth <= customWidth) {
  const rem = Math.floor(pageWidth / customWidth * 100) / 100;
  initCaptcha(rem);
}

Method call descriptions

You can call the corresponding method of the Captcha instance. The following methods are not supported for the first verification in no-captcha mode.

Method name

Description

Example

Scenario

show

Displays the Captcha element and mask.

captcha.show()

Use this when you need the Captcha dialog box to pop up automatically without a button click.

hide

Hides or closes the Captcha element and mask.

captcha.hide()

Use this when you need the Captcha dialog box to close automatically without a button click.

Returned data

When you integrate with Captcha 2.0 using the V3 client architecture for behavioral verification, the Captcha server verifies the user's behavior to determine whether the request is from a machine. The server then returns a Captcha code and other parameters to your client. You can view the returned data using the Network feature of your browser. For more information, see Data returned by the V3 client architecture.

lQLPJxFSi2GYDIHNBHTNCpawwjNH3sY_CI4IOehh6YNsAQ_2710_1140

Captcha:Integrate with Web and H5 clients using the V3 architecture

Prerequisites

Method overview

Procedure

Step 1: Add the AliyunCaptchaConfig global variable

Step 2: Dynamically import the Captcha JS file

Step 3: Call the initializer method to initialize Captcha.

Code example

Parameter descriptions

AliyunCaptchaConfig parameters

initAliyunCaptcha parameters

Method call descriptions

Returned data

Download V3 client architecture demos