常规验证码

常规验证码包括:滑块拼图、文字点选、图标点选、短信上行。

兼容性

IE7+、Chrome、Firefox、Safari、Opera、主流手机浏览器、iOS 及 Android上的内嵌Webview。

开始使用

引入初始化JS

  • 方案一:包含宕机方案(推荐)

注释: 当易盾服务器宕机了,请求验证码失败超过一定次数(示例代码中默认为3次,可配置),最后一次会触发宕机逻辑,宕机表现为:web端提示“前方拥堵,已自动跳过验证”,app端自动关闭验证框,验证码直接验证通过,用户可进行后续业务操作,免受宕机影响。

示例地址如下:

https://github.com/yidun/captcha-java-demo/blob/master/src/main/webapp/index.js

  • 方案二:简单接入版
  <!-- http示例如下: -->
  <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>

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

  <!-- 地址中的t参数强烈建议设置为分钟级别时间戳,避免该文件被浏览器长时间缓存,示例见完整示例 -->

调用初始化函数

initNECaptchaWithFallback(config, onload, onerror)

// initNECaptchaWithFallback为全局函数,可直接调用;若使用方案二引用初始化js,则函数名为initNECaptcha
initNECaptchaWithFallback({
    // config对象,参数配置
    captchaId: '从易盾申请的captchaId',
    element: '#captcha',
    mode: 'float',
    width: '320px'
}, function  onload (instance) {
    // 初始化成功后得到验证实例instance,可以调用实例的方法
}, function  onerror (err) {
    // 初始化失败后触发该函数,err对象描述当前错误信息
})

参数配置

这里指初始化时传入的config对象,即调用初始化函数initNECaptchaWithFallback时传入的第一个参数。智能无感知验证码设置参数有些不同,详见表格下方特别说明。

参数参数类型必填默认说明
captchaIdstring验证码id
modestringPC端默认"float",移动端默认"popup"验证码模式,常规验证码三种模式可选:"float"(触发式)、"embed"(嵌入式)、"popup"(弹出式),示例demo
elementstring/HTMLElement*容器元素或容器元素选择器。当mode是"popup"且用户使用表单提交时,必填;mode是"float"或"embed"时均是必填
protocolstring与用户网站的网络协议一致验证码传输数据使用的网络协议,可选:"http""https"
widthnumber |string"auto"验证按钮宽度,推荐使用宽度260px-400px。类型为string时,支持后缀pxrem%,类型为number时,内部会将其转换成px单位的值。"auto"时,其宽度与容器元素宽度一致。mode"popup"时,百分比单位无效
langstring"zh-CN"验证码语言选项。支持"zh-CN"-简体中文"、"zh-TW"-繁体中文、"en"-英语、"ja"-日语、"ko"-韩语、"th"-泰语、"vi"-越南语、"fr"-法语、"ru"-俄语、"ar"-阿拉伯语、"ge"德语、"it"意大利语、"he"希伯来语、"hi"印地语、"id"印尼语、"my"缅甸语、"lo"老挝语、"ms"马来语、"pl"波兰语、"pt"葡萄牙语、"es"西班牙文、"tr"土耳其语
appendTostring/HTMLElement验证码弹框的指定区域元素或者指定区域元素选择器。该配置仅在popup模式有效。请注意,指定区域的元素必须为非静态定位
onReadyfunctionNECaptcha所有工作准备就绪,用户可以使用验证码时触发该回调。具体使用见完整示例
onVerifyfunction验证码验证结束回调函数。具体使用见完整示例
onClosefunction验证码关闭弹框后回调函数。具体使用见完整示例
enableClosebooleanfalse由业务方控制验证码弹框关闭,具体使用见完整示例
extraDataString/Function如果需要在check阶段透传业务数据,可以使用extraData配置,支持字符串和函数,函数可以解决动态数据问题。当调用二次校验结果接口时,会原样返回该字段,详见后端响应参数

特别注意

对于指定弹框区域的验证码,参数appendTo表示的元素必须为非静态定位,即position不能为static。

实例方法

这里指initNECaptchaWithFallback初始化成功,onload触发时传入的实例的方法。

  • refresh:刷新验证码,获取新的验证信息,具体见onVerify示例

  • destroy:销毁当前实例

  • popUp:当验证码是常规验证码并且mode为"popup"时,可调用该实例方法弹出验证码进行验证

  • close:当验证码为popup弹框样式,且开启enableClose时,可调用该实例方法关闭验证码弹框

示例:

initNECaptchaWithFallback(config, function onload (instance) {
    // 可在此处调用实例方法
}, onerror)

完整示例

使用时间戳引入初始化js (仅适用引入js方案二)

  var url = 'http://cstaticdun.126.net/load.min.js' + '?t=' + getTimestamp(1 * 60 * 1000) // 时长1分钟,建议时长分钟级别
  loadScript(url, function () {
    // 进行初始化验证码等后续逻辑
    // initNECaptcha({
    //   captchaId: '从易盾申请的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)
  }

使用popup弹出模式

  • 当验证码 mode为 ‘popup’ 时,可以通过调用实例的 popUp 接口进行手动验证。

  • 验证码验证成功之后在 onVerify 的回调里面做实际的提交行为。

<!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>验证码示例-popup模式</title>
</head>
<body>
<button id="j-popup">点击弹出验证码</button>
<div id="captcha"></div>
<script  charset="UTF-8" type="text/javascript" src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
<!-- 地址中的t参数强烈建议设置为分钟级别时间戳,避免该文件被浏览器长时间缓存 -->
<script>
  var captchaIns;
  initNECaptcha({
    element: '#captcha',
    captchaId: '从易盾申请的captchaId',
    mode: 'popup',
    width: '320px',
    onClose: function () {
      // 弹出关闭结束后将会触发该函数
    }
  }, function (instance) {
    // 初始化成功后得到验证实例instance,可以调用实例的方法
    captchaIns = instance
  }, function (err) {
    // 初始化失败后触发该函数,err对象描述当前错误信息
  })

  // 监听button的点击事件,弹出验证码
  document.getElementById('j-popup').addEventListener('click', function () {
    captchaIns && captchaIns.popUp()
  })
</script>
</body>
</html>

使用onVerify获取验证结果回调

<!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">
  验证码示例
</head>
<body>
  <div class="form-container">
    <input  type="text" name="username" id="username" placeholder="用户名">
    <input  type="password" name="password" id="password" placeholder="密码">
    <div id="captcha"></div> <!-- 验证码容器元素 -->
    登录
  </div>
  <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
  <!-- 地址中的t参数强烈建议设置为分钟级别时间戳,避免该文件被浏览器长时间缓存 -->
  <script>
    var captchaIns;

    initNECaptcha({
      captchaId: '从易盾申请的captchaId',
      element: '#captcha',
      mode: 'float',
      width: 320,
      onReady: function (instance) {
     // 验证码一切准备就绪,此时可正常使用验证码的相关功能
      },
      onVerify: function (err, data) {
        /**
         * 第一个参数是err(Error的实例),验证失败才有err对象
         * 第二个参数是data对象,验证成功后的相关信息,data数据结构为key-value,如下:
         * {
         *   validate: 'xxxxx' // 二次验证信息
         * }
        **/
        if (err) return  // 当验证失败时,内部会自动refresh方法,无需手动再调用一次
        // 点击登录按钮后可调用服务端接口,以下为伪代码,仅作示例用
        ajax('/login', {
          captchaId: '从易盾申请的captchaId',
          username: $('#username').val(),
          password: $('#password').val(),
          validate: data.validate
        }, function onsuccess (data) {
          // if (loginFail) {
          // 密码错误等原因导致登陆失败,业务上若需要刷新验证码,可调用refresh方法
          //   captchaIns && captchaIns.refresh()
          // } else {
          // 登录成功后,相关处理逻辑
          // }
        })
      }
    }, function onload (instance) {
      // 初始化成功
      captchaIns = instance
    }, function onerror (err) {
      // 验证码初始化失败处理逻辑,例如:提示用户点击按钮重新初始化
    })
    </script>
</body>
</html>

使用appendTo(用于指定弹框区域)

<!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">
  验证码示例

  <style type="text/css">
    #appendWrap {
      position: relative;
    }
  </style>
</head>
<body>
  <div class="form-container" id="appendWrap">
    <button id="j-popup">点击弹出验证码</button>
    <div id="captcha"></div>
  </div>
  <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
  <!-- 地址中的t参数强烈建议设置为分钟级别时间戳,避免该文件被浏览器长时间缓存 -->
  <script>
    initNECaptcha({
      captchaId: '从易盾申请的captchaId',
      element: '#captcha',
      mode: 'popup',
      width: '320px',
      appendTo: '#appendWrap'
    }, function onload (instance) {
      // 初始化成功
      captchaIns = instance
    }, function onerror (err) {
      // 验证码初始化失败处理逻辑,例如:提示用户点击按钮重新初始化
    })
    
    // 监听button的点击事件,弹出验证码
    document.getElementById('j-popup').addEventListener('click', function () {
      captchaIns && captchaIns.popUp()
    })
  </script>
</body>
</html>

使用form表单

<!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>验证码示例</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> <!-- 验证码容器元素 -->
       <button type="submit">登录</button>
     </form>
   <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
   <!-- 地址中的t参数强烈建议设置为分钟级别时间戳,避免该文件被浏览器长时间缓存 -->
   <script>
    initNECaptcha({
      captchaId: '从易盾申请的captchaId',
      element: '#captcha',
      mode: 'float',
      width: 320
    }, function onload (instance) {
      // 初始化成功后,用户输入对应用户名和密码,以及完成验证后,直接点击登录按钮即可
    }, function onerror (err) {
      // 验证码初始化失败处理逻辑,例如:提示用户点击按钮重新初始化
    })
    </script>
</body>
</html>

特别说明

  • onloadonReady的区别:
    onloadonReady触发时,均会返回验证码的实例,即传入的第一个参数。二者触发时机有所不同,onload触发时,初始化函数结束和完成实例的生成,注意这并不代表验证码是可用的(比如验证码相关背景图片和信息并没有加载),此方法只触发一次。onReady触发时,说明验证码准备就绪(比如背景图片等信息均已加载),onReady只触发一次。
Online Chat Tel:95163223