## Compatibility

IE7+,Chrome,Firefox,Safari,Opera,main stream mobile browser,and Webview embedded in iOS and Android

## Come into use
### Introduce JS initialization
Code (html):
  <!-- http example -->
  <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>

  <!-- https example -->
  <script src="https://cstaticdun.126.net/load.min.js?t=201903281201"></script>

  <!-- The t parameter in the address is strongly recommended to be set to the minute level timestamp to prevent the file from being cached by the browser for a long time. See the full example for an example-->

### Call the initialization function

initNECaptcha(config, onload, onerror)

Code (js):
// initNECaptcha is a global funciton,which can be directly called
initNECaptcha({
    // config object, parameter configuration
    captchaId: 'your captchaId',
    element: '#captcha',
    mode: 'float',
    width: '320px'
}, function  onload (instance) {
    // The method of calling the verification instance acquired upon success of initialization
}, function  onerror (err) {
    // This function is triggered upon failure of initialization, err object describes the current error message
})

## normal type captcha

Normal type captcha includ: Slide Captcha,Icon click Captcha

### Parameter configuration

It refers to the config object introduced upon initialization, i.e. the first parameter introduced upon calling the initialization function initNECaptcha

Parameter | Parameter type | Not null | default | Description
captchaId | string | Yes | None | CAPTCHA ID
mode | string | NO | It's "float" by default at the PC end, and "popup" by default at the mobile end | The captcha is selectable in three modes: "float"(trigger mode), "embed"(embedded mode) , and "popup"(popup mode)
element | string/HTMLElement | * | None | Container element or container element selector When the mode is "popup" and the user uses a form for submission, it's compulsory to fill in; When the mode is "float" or "embed", it's compulsory to fill in;
protocol | string | No | Consistent with the user website's network protocol | Network protocol used for captcha transmission, which is selectable: "http", "https"
width | number |string | No | "auto" | Verification button width, recommended at 260px-400px. When the type is a string, the suffix of px, rem and % is supported, and when the type is a number, it will be converted to values of the px unit internally . In case of "auto", the width is consistent with the container element width.In case of "popup",the % is invalid
lang | string | No | "zh-CN" | Captcha language option."zh-CN"-simplified Chinese ","zh-TW"-traditional Chinese,"en"-English,"ja"-Japanese,"ko"-Korean,"th"-Thai,"vi"-Vietnamese,"fr"-French,"ru"-Russian,"ar"-Arabic
appendTo | string/HTMLElement | No | None | The specified area element of the captcha bulletin or the specified area element selector. This configuration is only valid in popup mode.Note that the elements of the specified area must be non-statically positioned
onReady | function | No | None | When all work for NECaptcha is prepared and ready, the user can trigger the call-back upon using the captcha. See the complete example for specific use
onVerify | function | No | None | Call-back function upon verification completion of captcha. See the complete example for specific use
onClose | function | No | None | Call-back function upon Close the captcha popup.See the complete example for specific use
enableClose | boolean | No | false | The captcha is closed by the business party.See the complete example for specific use
extraData | String/Function | No | None | If you need to transparently transmit business data during the check phase, you can use the extraData configuration, surpport for string and function,Function can solve dynamic data problems.When the secondary verification result interface is called, the field will be returned as it is. SeeBack-end Integration (https://support.dun.163.com/documents/312371656298516480?docId=640316992119705600)

[md-attention]

Pay attention:

For the captcha of the specified popup area, the element represented by the parameter appendTo must be non-static positioning, that is, the position cannot be static.

### Instance method

It refers to the method of introduction of the instance upon triggering onload upon successful initialization of initNECaptcha.

- refresh：Refresh the captcha and acquire the new verification information,see onVerify example

- destroy：Destroy the current instance

- popUp：When the mode is popup,this instance method can be called to pop up the captcha for verification

- close：：When the mode is popup,and use function enableClose,The instance method can be called to close the captcha bulletin

For example：

Code (js):
initNECaptchaWithFallback(config, function onload (instance) {
    // The instance method can be called here, such as instance.refresh() 
}, onerror)

### Complete example
#### Use initialization timestamp to introduce initialization js
Code (js):
  var url = 'http://cstaticdun.126.net/load.min.js' + '?t=' + getTimestamp(1 * 60 * 1000) // Duration 1 minute, recommended time minute level
  loadScript(url, function () {
    // Perform subsequent logic such as initialization verification code
    // initNECaptcha({
    //   captchaId: 'your captchaId',
    //   element: '#captcha',
    //   mode: 'float',
    //   width: '320px'
    // })
  })
  
  function getTimestamp (msec) {
    msec = !msec && msec !== 0 ? msec : 1
    return parseInt((new Date()).valueOf() / msec, 10)
  }
  
  function loadScript (src, cb) {
    var head = document.head || document.getElementsByTagName('head')[0]
    var script = document.createElement('script')

    cb = cb || function () {}

    script.type = 'text/javascript'
    script.src = src

    if (!('onload' in script)) {
      script.onreadystatechange = function () {
        if (this.readyState !== 'complete' && this.readyState !== 'loaded') return
        this.onreadystatechange = null
        cb(script)
      }
    }

    script.onload = function () {
      this.onload = null
      cb(script)
    }

    head.appendChild(script)
  }

#### Use popup mode
- when captcha mode is "popup" ,you can do this manually by calling the instance's popUp interface.

- After the captcha is successfully verified, the actual commit behavior is made in the callback of onVerify.

Code (html):
<!DOCTYPE html>
<html lang="zh-CN">
<head>
   <meta  charset="UTF-8">
   <meta  name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
   <meta  http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Captcha example for popup mode</title>
</head>
<body>
<button id="j-popup">Click to pop up captcha</button>
<div id="captcha"></div>
 <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
  <!-- The t parameter in the address is strongly recommended to be set to the minute level timestamp to prevent the file from being cached by the browser for a long time. See the full example for an example -->
<script>
  var captchaIns;
  initNECaptcha({
    element: '#captcha',
    captchaId: 'your captchaId',
    mode: 'popup',
    width: '320px',
    onClose: function () {
      // This function will be triggered when the popup is closed
    }
  }, function (instance) {
    // Upon initialization success, an instance of the verification instance is obtained, and the method of the instance can be called.
    captchaIns = instance
  }, function (err) {
    // The function is triggered after the initialization fails, and the err object describes the current error message.
  })

  // Monitor button click event, pop up captcha 
  document.getElementById('j-popup').addEventListener('click', function () {
    captchaIns && captchaIns.popUp()
  })
</script>
</body>
</html>

#### Use onVerify to get verification result callback
Code (html):
<!DOCTYPE html>
<html lang="en">
<head>
   <meta  charset="UTF-8">
   <meta  name="viewport" content="width=device-width, initial-scale=1.0">
   <meta  http-equiv="X-UA-Compatible" content="ie=edge">
  Captcha example
</head>
<body>
  <div class="form-container">
    <input  type="text" name="username" id="username" placeholder="usename">
    <input  type="password" name="password" id="password" placeholder="password">
    <div id="captcha"></div> <!-- Captcha container element -->
    Login
  </div>
  <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
  <!-- The t parameter in the address is strongly recommended to be set to the minute level timestamp to prevent the file from being cached by the browser for a long time. See the full example for an example -->
  <script>
    var captchaIns;

    initNECaptcha({
      captchaId: 'your captchaId',
      element: '#captcha',
      mode: 'float',
      width: 320,
      onReady: function (instance) {
     // The captcha is ready, and relevant functions of the captcha can be used normally
      },
      onVerify: function (err, data) {
        /**
         * The first parameter is err (instance of Error), and the error object will be available only upon failure of verification 
         * The second parameter is the data object, which refers to relevant information after successful verification. The structure of the data is key-value, as follows: 
         * {
         *   validate: 'xxxxx' // Secondary verification information 
         * }
        **/
        if (err) return  // When the verification fails, the internal refresh method is automatically used, no need to manually call again.
        //click the logon button to call the server terminal interface. The following is false code, only for example.
        ajax('/login', {
          captchaId: 'your captchaId',
          username: $('#username').val(),
          password: $('#password').val(),
          validate: data.validate
        }, function onsuccess (data) {
          // if (loginFail) {
          // If the password is incorrect, the login fails. If you need to refresh the verification code, you can call the "refresh" method.
          //   captchaIns && captchaIns.refresh()
          // } else {
          // relevant processing logics upon successful logon
          // }
        })
      }
    }, function onload (instance) {
      // Initialization succeeds 
      captchaIns = instance
    }, function onerror (err) {
      // Processing logic of captcha initialization failure, e.g.: Remind the user to click the button for reinitialization 
    })
    </script>
</body>
</html>

#### Use appentTo(Used to specify the area of popup)
Code (html):
<!DOCTYPE html>
<html lang="en">
<head>
   <meta  charset="UTF-8">
   <meta  name="viewport" content="width=device-width, initial-scale=1.0">
   <meta  http-equiv="X-UA-Compatible" content="ie=edge">
  Captcha example

  <style type="text/css">
    #appendWrap {
      position: relative;
    }
  </style>
</head>
<body>
  <div class="form-container" id="appendWrap">
    <button id="j-popup">Click to popup captcha</button>
    <div id="captcha"></div>
  </div>
  <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
  <!-- The t parameter in the address is strongly recommended to be set to the minute level timestamp to prevent the file from being cached by the browser for a long time. See the full example for an example -->
  <script>
    initNECaptchaWithFallback({
      captchaId: 'your captchaId',
      element: '#captcha',
      mode: 'popup',
      width: '320px',
      appendTo: '#appendWrap'
    }, function onload (instance) {
      // Initialization succeeds 
      captchaIns = instance
    }, function onerror (err) {
      // Processing logic of captcha initialization failure, e.g.: Remind the user to click the button for reinitialization 
    })
    
    // Listen to the click event of the button, pop up the verification code
    document.getElementById('j-popup').addEventListener('click', function () {
      captchaIns && captchaIns.popUp()
    })
  </script>
</body>
</html>

#### Use form
Code (html):
<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <meta  name="viewport" content="width=device-width, initial-scale=1.0">
   <meta  http-equiv="X-UA-Compatible" content="ie=edge">
<title>Captcha example</title>
</head>
<body>
   <form action="/login" method="post">
   <input  type="text" name="username" placeholder="用户名">
   <input  type="password" name="password" placeholder="密码">
   <input  type="hidden" name="captchaId" value="从易盾申请的captchaId">
    <div id="captcha"></div> <!-- Captcha container element -->
       <button type="submit">Login</button>
     </form>
   <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
   <!-- The t parameter in the address is strongly recommended to be set to the minute level timestamp to prevent the file from being cached by the browser for a long time. See the full example for an example -->
   <script>
    initNECaptchaWithFallback({
      captchaId: 'your captchaId',
      element: '#captcha',
      mode: 'float',
      width: 320
    }, function onload (instance) {
      // Upon initialization success, the user enters the corresponding user name and password and completes the verification, and then directly clicks the login button 
    }, function onerror (err) {
      // Processing logic of captcha initialization failure, e.g.: Remind the user to click the button for reinitialization 
    })
    </script>
</body>
</html>

## Smart Captcha
### Parameter configuration

It refers to the config object introduced upon initialization, i.e. the first parameter introduced upon calling the initialization function initNECaptcha

Parameter | Parameter type | Not null | default | Description
captchaId | string | Yes | None | CAPTCHA ID
mode | string | NO | None | The captcha mode,Can set "bind" mode, bind its own button mode; if not set, it is the captcha button mode
element | string/HTMLElement | * | None | Container element or container element selector
protocol | string | No | Consistent with the user website's network protocol | Network protocol used for captcha transmission, which is selectable: "http", "https"
width | number |string | No | "auto" | Verification button width, recommended at 260px-400px. When the type is a string, the suffix of px, rem and % is supported, and when the type is a number, it will be converted to values of the px unit internally . In case of "auto", the width is consistent with the container element width.In case of "popup",the % is invalid
lang | string | No | "zh-CN" | Captcha language option."zh-CN"-simplified Chinese ","zh-TW"-traditional Chinese,"en"-English,"ja"-Japanese,"ko"-Korean,"th"-Thai,"vi"-Vietnamese,"fr"-French,"ru"-Russian,"ar"-Arabic
appendTo | string/HTMLElement | No | None | The specified area element of the captcha bulletin or the specified area element selector. This configuration is only valid in popup mode.Note that the elements of the specified area must be non-statically positioned
onReady | function | No | None | When all work for NECaptcha is prepared and ready, the user can trigger the call-back upon using the captcha. See the complete example for specific use
onVerify | function | No | None | Call-back function upon verification completion of captcha. See the complete example for specific use
onClose | function | No | None | Call-back function upon Close the captcha popup.See the complete example for specific use
enableClose | boolean | No | false | The captcha is closed by the business party.See the complete example for specific use
extraData | String/Function | No | None | If you need to transparently transmit business data during the check phase, you can use the extraData configuration, surpport for string and function,Function can solve dynamic data problems.When the secondary verification result interface is called, the field will be returned as it is. SeeBack-end Integration (http://support.dun.163.com/documents/15588062143475712?docId=69218161355051008)

[md-attention]

Pay attention:

For the Senseless Captcha, when the mode is not set, the width setting is invalid, the captcha button width is consistent with the container width, and the container width is at least 240px.when mode is bind,the captcha width is equal to the width value.

For the captcha of the specified popup area, the element represented by the parameter appendTo must be non-static positioning, that is, the position cannot be static.

### Instance method

It refers to the method of introduction of the instance upon triggering onload upon successful initialization of initNECaptcha.

- refresh：Refresh the captcha and acquire the new verification information,see onVerify example

- destroy：Destroy the current instance

- verify：When the mode is bind,this instance method can be called to pop up the captcha for verification

- close：：When the mode is bind,and use function enableClose,The instance method can be called to close the captcha bulletin

For example：

Code (js):
initNECaptchaWithFallback(config, function onload (instance) {
    // The instance method can be called here, such as instance.refresh() 
}, onerror)

### Complete example
#### Use initialization timestamp to introduce initialization js
Code (js):
  var url = 'http://cstaticdun.126.net/load.min.js' + '?t=' + getTimestamp(1 * 60 * 1000) // Duration 1 minute, recommended time minute level
  loadScript(url, function () {
    // Perform subsequent logic such as initialization verification code
    // initNECaptcha({
    //   captchaId: 'your captchaId',
    //   element: '#captcha',
    //   width: '320px'
    // })
  })
  
  function getTimestamp (msec) {
    msec = !msec && msec !== 0 ? msec : 1
    return parseInt((new Date()).valueOf() / msec, 10)
  }
  
  function loadScript (src, cb) {
    var head = document.head || document.getElementsByTagName('head')[0]
    var script = document.createElement('script')

    cb = cb || function () {}

    script.type = 'text/javascript'
    script.src = src

    if (!('onload' in script)) {
      script.onreadystatechange = function () {
        if (this.readyState !== 'complete' && this.readyState !== 'loaded') return
        this.onreadystatechange = null
        cb(script)
      }
    }

    script.onload = function () {
      this.onload = null
      cb(script)
    }

    head.appendChild(script)
  }

#### Use bind mode
- when captcha mode is "bind" ,you can do this manually by calling the instance's verify interface.

- The advantage of this form is that the user can do some custom events (such as form parameter processing verification) before verifying the captcha, and then decide whether to call the verification interface.

- After the captcha is successfully verified, the actual commit behavior is made in the callback of onVerify.

Code (html):
<!DOCTYPE html>
<html lang="zh-CN">
<head>
   <meta  charset="UTF-8">
   <meta  name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
   <meta  http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Captcha example for bind mode</title>
</head>
<body>

<form action="/login" method="post">
   <input  type="text" name="username" placeholder="username">
   <input  type="password" name="password" placeholder="password">
   <input  type="hidden" name="captchaId" value="your captchaId">
   <div id="captcha"></div> <!-- Captcha container element -->
   <button type="submit" id="submit-btn">Login</button>
</form>

<script charset="UTF-8" type="text/javascript" src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
<!-- The t parameter in the address is strongly recommended to be set to the minute level timestamp to prevent the file from being cached by the browser for a long time. See the full example for an example -->
<script>

    var captchaIns;
    initNECaptchaWithFallback({
        element: '#captcha',
        captchaId: 'your captchaId',
        mode: 'bind', // Mode can be set to bind only for senceless captcha
        width: '320px',
        //enableClose: true, // The  captcha is closed by the business party.
        onVerify: function(err){
            // After the user is successfully verified, the actual submission behavior is performed.
            // todo
            // if (!err) {
              // After the verification is successful, call the close method to close the popup (called when enableClose is true)
              //captchaIns.close()
            //}
        }
    }, function (instance) {
        // Upon initialization success, an instance of the verification instance is obtained, and the method of the instance can be called.
        captchaIns = instance
    }, function (err) {
        // The function is triggered after the initialization fails, and the err object describes the current error message.
    })
    // Listen for the click event of the button that needs to be bound, and manually call the instance's verify method to verify
    document.getElementById('submit-btn').addEventListener('click', function (e) {
      e.preventDefault()
      //  if (doSomething()) {               // Do some customization before verification
            captchaIns && captchaIns.verify ()  // Manually call the verify method
       // }
    })
</script>
</body>
</html>

#### Use onVerify to get verification result callback
Code (html):
<!DOCTYPE html>
<html lang="en">
<head>
   <meta  charset="UTF-8">
   <meta  name="viewport" content="width=device-width, initial-scale=1.0">
   <meta  http-equiv="X-UA-Compatible" content="ie=edge">
  Captcha example
</head>
<body>
  <div class="form-container">
    <input  type="text" name="username" id="username" placeholder="usename">
    <input  type="password" name="password" id="password" placeholder="password">
    <div id="captcha"></div> <!-- Captcha container element -->
    Login
  </div>
  <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
  <!-- The t parameter in the address is strongly recommended to be set to the minute level timestamp to prevent the file from being cached by the browser for a long time. See the full example for an example -->
  <script>
    var captchaIns;
    initNECaptcha({
      captchaId: 'your captchaId',
      element: '#captcha',
      width: 320px,
      onReady: function (instance) {
     // The captcha is ready, and relevant functions of the captcha can be used normally
      },
      onVerify: function (err, data) {
        /**
         * The first parameter is err (instance of Error), and the error object will be available only upon failure of verification 
         * The second parameter is the data object, which refers to relevant information after successful verification. The structure of the data is key-value, as follows: 
         * {
         *   validate: 'xxxxx' // Secondary verification information 
         * }
        **/
        if (err) return  // When the verification fails, the internal refresh method is automatically used, no need to manually call again.
        //click the logon button to call the server terminal interface. The following is false code, only for example.
        ajax('/login', {
          captchaId: 'your captchaId',
          username: $('#username').val(),
          password: $('#password').val(),
          validate: data.validate
        }, function onsuccess (data) {
          // if (loginFail) {
          // If the password is incorrect, the login fails. If you need to refresh the verification code, you can call the "refresh" method.
          //   captchaIns && captchaIns.refresh()
          // } else {
          // relevant processing logics upon successful logon
          // }
        })
      }
    }, function onload (instance) {
      // Initialization succeeds 
      captchaIns = instance
    }, function onerror (err) {
      // Processing logic of captcha initialization failure, e.g.: Remind the user to click the button for reinitialization 
    })
    </script>
</body>
</html>

#### Use appentTo(Used to specify the area of popup)
Code (html):
<!DOCTYPE html>
<html lang="en">
<head>
   <meta  charset="UTF-8">
   <meta  name="viewport" content="width=device-width, initial-scale=1.0">
   <meta  http-equiv="X-UA-Compatible" content="ie=edge">
  Captcha example

  <style type="text/css">
    #appendWrap {
      position: relative;
    }
  </style>
</head>
<body>
  <div class="form-container" id="appendWrap">
    <button id="j-popup">Click to popup captcha</button>
    <div id="captcha"></div>
  </div>
  <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
  <!-- The t parameter in the address is strongly recommended to be set to the minute level timestamp to prevent the file from being cached by the browser for a long time. See the full example for an example -->
  <script>
    initNECaptchaWithFallback({
      captchaId: 'your captchaId',
      element: '#captcha',
      mode: 'popup',
      width: '320px',
      appendTo: '#appendWrap'
    }, function onload (instance) {
      // Initialization succeeds 
      captchaIns = instance
    }, function onerror (err) {
      // Processing logic of captcha initialization failure, e.g.: Remind the user to click the button for reinitialization 
    })
    
    // Listen to the click event of the button, pop up the verification code
    document.getElementById('j-popup').addEventListener('click', function () {
      captchaIns && captchaIns.popUp()
    })
  </script>
</body>
</html>

#### Use form
Code (html):
<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <meta  name="viewport" content="width=device-width, initial-scale=1.0">
   <meta  http-equiv="X-UA-Compatible" content="ie=edge">
<title>Captcha example</title>
</head>
<body>
   <form action="/login" method="post">
   <input  type="text" name="username" placeholder="uesername">
   <input  type="password" name="password" placeholder="password">
   <input  type="hidden" name="captchaId" value="your captchaId">
    <div id="captcha"></div> <!-- Captcha container element -->
       <button type="submit">Login</button>
     </form>
   <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
   <!-- The t parameter in the address is strongly recommended to be set to the minute level timestamp to prevent the file from being cached by the browser for a long time. See the full example for an example -->
   <script>
    initNECaptchaWithFallback({
      captchaId: 'your captchaId',
      element: '#captcha',
      mode: 'float',
      width: 320
    }, function onload (instance) {
      // Upon initialization success, the user enters the corresponding user name and password and completes the verification, and then directly clicks the login button 
    }, function onerror (err) {
      // Processing logic of captcha initialization failure, e.g.: Remind the user to click the button for reinitialization 
    })
    </script>
</body>
</html>

#### Special Note
- The difference betweenonloadandonReady:
When onload and onReady are triggered, an instance of the verification code is returned, which is the first parameter passed in.The trigger timing of the two is different. When the onload is triggered, the initialization function ends and the instance is generated,note that this does not mean that the captcha is available(For example, the captcha related background image and information are not loaded),This method only fires once . When onReady is triggered, it indicates that the verification code is ready (for example, the background image and other information are loaded), and onReady is only triggered once.