Captcha:Integrate Captcha 2.0 into a business client

Prerequisites

Captcha 2.0 is activated, and a verification scenario whose Client Type is Web or H5 is created. For more information, see Step 2: Create a verification scenario.

Integrate the initialization code of Captcha 2.0

Both the web and HTML5 clients support pop-up and embedded Captcha modes. In this example, the logon scenario is used to describe how to integrate the initialization code of Captcha 2.0 into the source code of a business client.

1. Reserve the Captcha page elements in the source code of the business client. In this example, the logon scenario is used.

   // Example of the source code of a business client
    const button = document.getElementById('button');
    button.onclick = function () {
      // Initiate a request to the backend.
      const result = await getWithParams('xx', { 
          yourBizParam... // The business parameter.
      });                
      const { bizResult } = result;
      if (bizResult) {
        // You are navigated to the corresponding page. In this example, the page https://www.aliyun.com/ is specified.
        window.location.href = 'https://www.aliyun.com/';
      }
    }
   
   // The code in the request body of the business client.
   <div id="space-semantic">
       <div id="embed-wrapper">
           <h2>Pop-up</h2>
           <div class="embed-wrapper">
               <div>
                   <label>Username:</label>
                   <input id="username-embed" class="biz-input">
               </div>
               <div>
                   <label>Password:</label>
                   <input id="password-embed" type="password" class="biz-input">
               </div>
               <div id="captcha-element"></div>  // The reserved Captcha page element, which is used to configure the element parameter in the initializer function.
               <button id="button" class="login-btn">Log On</button>
           </div>
       </div>
   </div>

2. Integrate the initialization code of Captcha 2.0 into the source code of the business client.

   Important

   • By default, JavaScript is loaded online to update the most recent security capabilities. If you pull code of earlier versions and deploy the code on your on-premises machine, the parameter values in the code cannot be updated. This is not recommended. You must manually update the code based on the update notifications of JavaScript versions.

   • We recommend that you do not repeatedly call the initAliyunCaptcha initialization method unless required. For example, if initialization parameters are modified, you can call the method. For more information, see Q1: What is the lifecycle of a CAPTCHA?

   Pop-up

   // 1. Integrate the main JavaScript code.
   <script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"></script>
   // 2. Create a <script> tag to call the initializer function initAliyunCaptcha.
   <script>
     let captcha;
     // Pop-up Captcha
     initAliyunCaptcha({
       SceneId: 'c9h3****', // The scenario ID. You can view the scenario ID on the Scenarios page of the Pop-up Captcha 2.0 console after you create a verification scenario.
       prefix: '89****', // The identity of the Captcha 2.0 instance that you purchase. You can view the identity of the Captcha 2.0 instance that you purchase on the Overview page of the Captcha 2.0 console after you activate Captcha 2.0.
       mode: 'popup', // The Captcha mode. A value of popup specifies the pop-up Captcha mode. You do not need to modify this parameter.
       element: '#captcha-element', // The element reserved on the page that is used to render a Captcha. The element is consistent with the reserved page element in the source code. 
       button: '#button', // The element that triggers the pop-up Captcha window. A value of button specifies that the captchaVerifyCallback function is triggered after you click Log On. You can modify the value of the element parameter based on the element that you actually use.
       captchaVerifyCallback: captchaVerifyCallback, // The callback function for the business request with Captcha verification. You do not need to modify this function.
       onBizResultCallback: onBizResultCallback, // The callback function for the business request verification result. You do not need to modify this function.
       getInstance: getInstance, // The function that is used to bind the Captcha 2.0 instance. You do not need to modify this function.
       slideStyle: {
         width: 360,
         height: 40,
       }, // The style of the slider Captcha. You can specify the width and height. Unit: pixel. The minimum width is 320 pixels.
       language: 'cn', // The language of the verification code. Valid values: cn: Simplified Chinese. tw: Traditional Chinese. en: English.
       region: 'cn' // The region to which the Captcha 2.0 instance belongs. Valid values: cn: Chinese mainland. sgp: Singapore.
     });
   
     // The function that is used to bind the Captcha 2.0 instance. This function is implemented in a fixed format and does not need to be modified.
     function getInstance(instance) {
       captcha = instance;
     }
   
     // The callback function for the business request with Captcha verification.
     /**
      * @name captchaVerifyCallback
      * @function
      * Request parameters: The following parameter is a verification parameter that is called back by the Captcha script. Directly pass this parameter to the business server instead of modifying it.
      * @params {string} captchaVerifyParam
      * Response parameters: The parameter names are fixed and the captchaResult parameter is required. If no business verification scenario is involved, the bizResult parameter is optional.
      * @returns {{captchaResult: boolean, bizResult?: boolean|undefined}} 
      */
     async function captchaVerifyCallback(captchaVerifyParam) {
       // 1. Initiate a business request to the backend. The Captcha verification result and the business result are returned.
       const result = await xxxx('http://The URL of your business request', {
           captchaVerifyParam: captchaVerifyParam, // The Captcha parameter.
           yourBizParam... // The business parameter.
       });
   
       // 2. Construct standard response parameters.
       const verifyResult = {
         captchaResult: result.captchaVerifyResult, // Required. Indicates whether the Captcha verification is passed. The value is of the BOOLEAN type.
         bizResult: returns the business verification result, // Optional. Indicates whether the business verification is passed. The value is of the BOOLEAN type. If no business verification scenario is involved, the bizResult parameter is left empty.
       };
       return verifyResult;
     }
   
     // The callback function for the business request verification result.
     function onBizResultCallback(bizResult) {
       if (bizResult === true) {
         // If the business verification is passed, you are navigated to the corresponding page. In this example, the page https://www.aliyun.com/ is specified.
         window.location.href = 'https://www.aliyun.com/';
       } else {
         // If the business verification fails, a message appears. In this example, the "The business verification failed." message is specified. 
         alert('The business verification failed. ');
       }
     }
   </script>

   Embedded

   // 1. Integrate the main JavaScript code.
   <script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"></script>
   // 2. Create a <script> tag to call the initializer function initAliyunCaptcha.
   <script>
     let captcha;
     // Embedded Captcha
     initAliyunCaptcha({
       SceneId: 'c9h3****', // The scenario ID. You can view the scenario ID on the Scenarios page of the Captcha 2.0 console after you create a verification scenario.
       prefix: '89****', // The identity of the Captcha 2.0 instance that you purchase. You can view the identity of the Captcha 2.0 instance that you purchase on the Overview page of the Captcha 2.0 console after you activate Captcha 2.0.
       mode: 'embed', // The Captcha mode. A value of embed specifies the embedded Captcha mode. You do not need to modify this parameter.
       element: '#captcha-element', // The element reserved on the page that is used to render a Captcha. The element is consistent with the reserved page element in the source code. 
       button: '#button', // The element that triggers the business request. A value of button specifies that the captchaVerifyCallback function is triggered after you click Log On. You can modify the value of the element parameter based on the element that you actually use.
       captchaVerifyCallback: captchaVerifyCallback, // The callback function for the business request with Captcha verification. You do not need to modify this function.
       onBizResultCallback: onBizResultCallback, // The callback function for the business request verification result. You do not need to modify this function.
       getInstance: getInstance, // The function that is used to bind the Captcha 2.0 instance. You do not need to modify this function.
       slideStyle: {
         width: 360,
         height: 40,
       }, // The style of the slider Captcha. You can specify the width and height. Unit: pixel. The minimum width is 320 pixels.
       language: 'cn', // The language of the verification code. Valid values: cn: Simplified Chinese. tw: Traditional Chinese. en: English.
       immediate: false, // Specifies whether to immediately call the captchaVerifyCallback function after verification.
       region: 'cn' // The region to which the Captcha 2.0 instance belongs. Valid values: cn: Chinese mainland. sgp: Singapore.
     });
   
     // The function that is used to bind the Captcha 2.0 instance. This function is implemented in a fixed format and does not need to be modified.
     function getInstance(instance) {
       captcha = instance;
     }
   
     // The callback function for the business request with Captcha verification.
     /**
      * @name verifyCaptchaCallback
      * @function
      * Request parameters: The following parameter is a verification parameter that is called back by the Captcha script. Directly pass this parameter to the business server instead of modifying it.
      * @params {string} captchaVerifyParam
      * Response parameters: The parameter names are fixed and the captchaResult parameter is required. If no business verification scenario is involved, the bizResult parameter is optional.
      * @returns {{captchaResult: boolean, bizResult?: boolean|undefined}} 
      */
     async function captchaVerifyCallback(captchaVerifyParam) {
       // 1. Initiate a business request to the backend. The Captcha verification result and the business result are returned.
       const result = await xxxx('http://The URL of your business request', {
           captchaVerifyParam: captchaVerifyParam, // The Captcha parameter.
           yourBizParam... // The business parameter.
       });
   
       // 2. Construct standard response parameters.
       const verifyResult = {
         captchaResult: result.captchaVerifyResult, // Required. Indicates whether the Captcha verification is passed. The value is of the BOOLEAN type.
         bizResult: returns the business verification result, // Optional. Indicates whether the business verification is passed. The value is of the BOOLEAN type. If no business verification scenario is involved, the bizResult parameter is left empty.
       };
       return verifyResult;
     }
   
     // The callback function for the business request verification result.
     function onBizResultCallback(bizResult) {
       if (bizResult === true) {
         // If the business verification is passed, you are navigated to the corresponding page. In this example, the page https://www.aliyun.com/ is specified.
         window.location.href = 'https://www.aliyun.com/';
       } else {
         // If the business verification fails, a message appears. In this example, the "The business verification failed." message is specified. 
         alert('The business verification failed. ');
       }
     }
   </script>

If you have questions about how to use Captcha 2.0, submit a ticket to contact technical support.

Parameter description

initAliyunCaptcha

function getInstance(instance) {
 captcha = instance;
 }

captchaVerifyCallback

• Request parameters

  Parameter	Type	Required	Default value	Description
  captchaVerifyParam	String	Yes	captchaVerifyParam	The Captcha parameter. The parameter is a verification parameter that is called back by the Captcha script. Directly pass this parameter to the business server instead of modifying it.

• Response parameters

  Parameter	Type	Default value	Description
  captchaResult	Boolean	No default value	Indicates whether the Captcha verification is passed.
  bizResult	Boolean	No default value	Indicates whether the business verification is passed. If no business verification scenario is involved, the bizResult parameter is optional.

Download client integration demos

• React-based integration demo

• Vue-based integration demo

• React-based demo for sending text messages