平台对接


V5验证前后端对接流程如下图所示:

前后端调用时序图

对接V5验证分为业务网站后台api对接以及业务前端代码引入两部分。

业务网站后台

获取验证Token及验证服务器(getToken)

用于网站后台定时通过V5控制台刷新获取验证所需要的Token及验证服务器地址。Token有效期为24小时。

请求方式:GET

调用示例:

curl -X GET 'https://{host}/openapi/getToken?appid=dff58e0476e34b5899d4027733f8c14b&timestamp=1564220208945&signature=6c8e8e38d11dddb08d5b5a8fc750db68'

Request入参说明:

参数名 说明 示例
appid 当前网站应用对应的App Id dff58e0476e34b5899d4027733f8c14b
timestamp 当前提交时的Unix时间戳,即北京时间1970-1-1 0:0:0到现在经过的毫秒数 1564220208945
signature 当前提交时的签名。详细见签名规则 6c8e8e38d11dddb08d5b5a8fc750db68'

Response返回格式:

{
    "success": true, //请求是否成功标识
    "data": {              //请求返回的消息体,详细以下列表说明
    "expiresIn": "86400000",
    "token": "e3e3d5d1aa4445e9bdde0bdb7eac37d6"
    }
}

返回参数说明:

参数名 说明 示例
token 返回当前有效的token e3e3d5d1aa4445e9bdde0bdb7eac37d6
expiresIn token有效时长单位毫秒 86400000'

获取验证结果(verify)

在前端完成验证后,业务网站后台向V5验证服务器调用接口获取验证结果。验证结果最长保留5分钟,在业务网站后台成功获取结果后立即删除。

请求方式:GET

调用示例:

curl -X GET 'https://{host}/openapi/verify?&verifyid=ee92ede662aa43c3a68c2a369fa19c70&token=644112d89ac54bac97cee06d42e2137c&timestamp=1564220208945&signature=6c8e8e38d11dddb08d5b5a8fc750db68'

Request入参说明:

参数名 说明 示例
host 验证节点域名 xxxx.verify5.com
verifyid 前端验证时返回的票据,由前端验证后返回 ee92ede662aa43c3a68c2a369fa19c70
token 当前有效的token 644112d89ac54bac97cee06d42e2137c
timestamp 当前提交时的Unix时间戳,即北京时间1970-1-1 0:0:0到现在经过的毫秒数 1564220208945
signature 当前提交时的签名。详细见签名规则
注:host不参与签名
6c8e8e38d11dddb08d5b5a8fc750db68

Response返回格式:

{
    "success": true, //请求是否成功或失败标识,true/false
}

前端对接

Web前端

1. 引入JS

在需要进行V5验证的页面,引入v5.js:

<script src="https://s.verify5.com/assets/latest/v5.js" type="text/javascript"></script>

2. 样式表

默认情况下,v5.js会检测当前页面环境并自动植入v5.css,开发者也可手动在页面植入css代码样式表:

<link rel="stylesheet" href="https://s.verify5.com/assets/latest/css/v5.css" type="text/css" />

3. JS API校验

<script>
    var v5=new com.strato.Verify5({//每次验证都要创建新的Verify5实例
        host:"Host",//从后台getToken接口获得
        token:"(Token)"//从后台getToken接口获得
    });
    v5.on("CANCEL",function(){
        //当用户取消验证时触发
    });
    v5.verify(function(result){
        var success=result.success;
        if(success){
            var verifyId=result.verifyId;
            //TODO 将verifyId提交到应用服务器请求二次验证
        }
    });
<script>

4. npm引入方式


    npm install verify5-html --save


    import Verify5 from 'verify5-html'


    let v5=new Verify5({//每次验证都要创建新的Verify5实例
        host:"Host",//从后台getToken接口获得
        token:"(Token)"//从后台getToken接口获得
    };
    v5.on("CANCEL",function(){
        //当用户取消验证时触发
    });
    v5.verify(function(result){
        var success=result.success;
        if(success){
            var verifyId=result.verifyId;
            //TODO 将verifyId提交到应用服务器请求二次验证
        }
    });

5. Data API校验

V5支持通过自定义属性v5-config自动初始化UI控件。语法为:

<div v5-config="{ name:'v5', host:'(Host)', token:'(Token)' }" ></div>

v5.js会在页面加载完成后自动生成验证按钮组件,如下图效果:

当用户点击按钮并验证通过时,会自动在div内生成hidden input:

<input id="v5container" type="hidden" name="{name}" value="{verifyId}" />

其中,{name}为v5-config中传入的name(示例中为 "v5" ),{verifyId}为控件自动生成的唯一通过码,该字段需同业务表单一起提交至后台,并提交到验证服务器进行二次验证。

签名规则


签名生成方法如下:

对所有请求参数(包括公有参数和私有参数,但不包括 signature 参数),按照参数名ASCII码表升序顺序排序。如:foo=1f, bar=2B, foo_bar=3FB, baz=4baz 排序后的顺序是 bar=2B, baz=4baz, foo=1f, foobar=3FB。

将排序好的参数名和参数值构造成字符串,格式为:key1value1key2value2… 。根据上面的示例得到的构造结果为:bar2Bbaz4bazfoo1ffoobar3FB 。

选择与 appid 配对的 appkey ,加到上一步构造好的参数字符串之后,如 app=6308afb129ea00301bd7c79621d07591 ,则最后的参数字符串为:bar2Bbaz4bazfoo1ffoobar3FB6308afb129ea00301bd7c79621d07591。

把第3步拼装好的字符串采用 utf-8 编码,使用 MD5 算法对字符串进行摘要,计算得到 signature 参数值,将其加入到接口请求参数中即可。MD5 是128位长度的摘要算法,用16进制表示,一个十六进制的字符能表示4个位,所以签名后的字符串长度固定为32位十六进制字符(小写)。

签名生成示例代码(java):

/**
* 生成签名信息
* @paramappKey产品私钥
* @param params 接口请求参数名和参数值map,不包括signature参数名
* @return
*/
public static String genSignature(String appKey, Map params){
    // 1. 参数名按照ASCII码表升序排序
    String[] keys = params.keySet().toArray(new String[0]);
    Arrays.sort(keys);

    // 2. 按照排序拼接参数名与参数值
    StringBuilder sb = newStringBuilder();
    for (String key : keys) {
        sb.append(key).append(params.get(key));
    }
    // 3. 将secretKey拼接到最后
    sb.append(appKey);

    // 4. MD5是128位长度的摘要算法,转换为十六进制之后长度为32字符
    return DigestUtils.md5Hex(sb.toString().getBytes("UTF-8"));
}

API接口一览


/openapi/getToken

该接口用于网站后台定时通过V5控制台刷新获取验证所需要的Token及验证服务器地址。Token有效期为24小时。

请求方式:GET

调用示例:

curl -X GET 'https://{host}/openapi/getToken?appid=dff58e0476e34b5899d4027733f8c14b&timestamp=1564220208945&signature=6c8e8e38d11dddb08d5b5a8fc750db68'

Request入参说明:

参数名 说明 示例
appid 当前网站应用对应的App Id dff58e0476e34b5899d4027733f8c14b
timestamp 当前提交时的Unix时间戳,即北京时间1970-1-1 0:0:0到现在经过的毫秒数 1564220208945
signature 当前提交时的签名。详细见签名规则 6c8e8e38d11dddb08d5b5a8fc750db68

Response返回格式:

{
    "success": true, //请求是否成功标识
    "data": {        //请求返回的消息体,详细以下列表说明
        "expiresIn": "86400000",
        "token": "e3e3d5d1aa4445e9bdde0bdb7eac37d6"
    }
}

返回参数说明:

参数名 说明 示例
token 返回当前有效的token e3e3d5d1aa4445e9bdde0bdb7eac37d6
expiresIn token有效时长单位毫秒 86400000

/openapi/verify

获取验证结果。在前端完成验证后,业务网站后台向V5验证服务器调用接口获取验证结果。验证结果最长保留5分钟,在业务网站后台成功获取结果后立即删除。

请求方式:GET

调用示例:

curl -X GET 'https://{host}/openapi/verify?&verifyid=ee92ede662aa43c3a68c2a369fa19c70&token=644112d89ac54bac97cee06d42e2137c&timestamp=1564220208945&signature=6c8e8e38d11dddb08d5b5a8fc750db68'

Request入参说明:

参数名 说明 示例
host 验证节点域名 xxxx.verify5.com
verifyid 前端验证时返回的票据,由前端验证后返回 ee92ede662aa43c3a68c2a369fa19c70
token 当前有效的token 644112d89ac54bac97cee06d42e2137c
timestamp 当前提交时的Unix时间戳,即北京时间1970-1-1 0:0:0到现在经过的毫秒数 1564220208945
signature 当前提交时的签名。详细见签名规则
注:host不参与签名
6c8e8e38d11dddb08d5b5a8fc750db68'

Response返回格式:

{
    "success": true, //请求是否成功或失败标识,true/false
}

JS方法一览


class com.strato.Verify5(Object config)

v5构造函数,config参数包括:

ssl:boolean值,可以是true或者false,可不传,生产环境下默认为true。
host:即应用中的域名host
token:应用令牌,由服务端调用API(/openapi/getToken)获得

void on(String eventName,Function callback)事件监听。

eventName包括:

CANCEL:用户取消校验
DESTROY:控件控件销毁(当校验成功、取消、失败时均会触发,可用作校验结束标记)。

void verify(Function callback)

唤起校验窗口,当成功后触发callback。

callback接收result参数,包含两个属性:

success:校验是否通过
verifyId:校验通过后返回的唯一通过码

static com.strato.verify5.v5Field $(String id)

根据 id获取data api的对象实例,例如:

var field=com.strato.Verify5.$(" v5container" );

class com.strato.Verify5.v5Field()

data api的控件构造函数,一般无需手动实例化,可通过com.strato.Verify5.$方法获得对应的实例。

String getValue()

得到控件的校验结果(verifyId)

com.strato.Verify5 getVerify5()

得到对应的v5实例。


Android

待补充

Ios

待补充

小程序

待补充

Top