概述

本SDK为极验3.0验证安全系统的Node服务端开发库。封装了与极验API接口交互相关的细节,并提供了fallback功能。

环境要求

条目
兼容性 Node 4+
SDK 依赖 request
demo 依赖 express, body-parser, supervisor, express-session

本SDK,可以直接从GitHub上下载,然后引入目录中的gt-sdk.js文件,更推荐的方式是通过 npm 包管理器来安装 npm install gt3-sdk

资源下载

条目
文档对应的版本 2.x.x
产品结构流程 通讯流程
SDK地址 gt3-node-sdk
NPM安装 npm install gt3-sdk

安装

下载SDK

使用 git 从 Github 获取

git clone https://github.com/GeeTeam/gt3-node-sdk.git

手动下载获取

使用从Github下载.zip文件获取最新的sdk

下载地址:gt3-node-sdk

引入SDK

在 Node 项目中,通过 npm install gt3-sdk --save 安装该 SDK。然后通过以下方式引入:

var Geetest = require('gt3-sdk');

配置接口

Geetest 初始化后的实例拥有以下接口:

  1. 注册接口 register(data, callback)
  2. 二次验证接口 validate(fallback, result, callback)

在调用Geetest前请正确配置从极验3.0后台注册获取的公钥(captcha_id)和私钥(captcha_key)

代码示例

初始化

使用极验后台申请的 idkey 进行初始化:

var captcha = new Geetest({
geetest_id: 'xxx',
geetest_key: 'xxx'
});

register(data, callback) 获取 challenge(API1)

参数说明:

  • data 对象含有以下字段,为 null 表示不传:
    • client_type:客户端类型,值可以为'web'(pc浏览器),'h5'(手机浏览器,包括webview),'native'(原生APP ),'unknown'(未知)
    • ip_address: 客户端IP地址,'unknnow'表示未知
  • callback:注册接口回调函数

注意,宕机的状态需要用户保存,以便之后能正确调用validate接口进行二次验证。下面的例子中使用session来保持fallback。

captcha.register(null, function (err, data) {
if (err) {
console.error(err);
return;
}
if (!data.success) {
// 进入 fallback,如果一直进入此模式,请检查服务器到极验服务器是否可访问
// 可以通过修改 hosts 把极验服务器 api.geetest.com 指到不可访问的地址
// 为以防万一,你可以选择以下两种方式之一:
// 1. 继续使用极验提供的failback备用方案
req.session.fallback = true;
res.send(data);
// 2. 使用自己提供的备用方案
// todo
} else {
// 正常模式
req.session.fallback = false;
res.send(data);
}
});

validate(fallback, result, callback) 进行二次验证(API2)

参数说明:

  • fallback:此次session是否在宕机状态下,布尔值
  • result:前端验证结果,包含geetest_challengegeetest_validategeetest_seccode三个字段
  • callback:二次验证回调函数
captcha.validate(req.session.fallback, {
geetest_challenge: req.body.geetest_challenge,
geetest_validate: req.body.geetest_validate,
geetest_seccode: req.body.geetest_seccode
}, function (err, success) {
if (err) {
// 网络错误
res.send(err);
} else if (!success) {
// 二次验证失败
res.send("<h1 style='text-align: center'>登录失败</h1>");
} else {
res.send("<h1 style='text-align: center'>登录成功</h1>");
}
});

运行demo

通过 npm install 安装好依赖后,在SDK根目录下运行 npm start,然后使用浏览器访问地址 http://localhost:9977