业务安全风控AFD

    JavaScript安全SDK文档

    概述

    活动反作弊JS SDK为接入方H5页面提供安全环境检查,通过采集浏览器信息和用户操作数据进行风险分析。

    集成步骤

    流程说明

    1. 活动方完成接入审批流程,说明见接入流程
    2. 审批通过后,风控平台方颁发活动ID(KEY),提供JSSDK集成文档和data-app配置
    3. 业务方参考《昊天镜风控系统API》文档准备服务端参数(z,to和vw参数通过JSSDK接口获取后上传到服务端),提供活动页面URL用于JS风控验证
    4. 在H5活动页面中安装JS SDK,见安装示例
    5. 初始化JS SDK,见[初始化JS SDK](#初始化JS SDK)
    6. 调用JSSDK提供的hgz()接口获取安全SDK的ZID,见获取ZID接口

      • 为了提升风控效果,应统一改为使用JSSDK提供的接口获取ZID,不应再使用活动方端能力获取ZID
      • 每次切换活动场景时都需要调用hgz()重新获取ZID
    7. 活动页面通过JSSDK接口获取JS风控参数to和vw的值,见获取JS风控参数值
    8. 用户提交活动,页面上传数据和风控参数到活动方服务器
    9. 活动方服务端填充接口所需参数(z、to和vw),访问昊天镜风控系统API查询风控结果

    JS SDK安装说明

    请将JS SDK安装在标签</ body >标记,以及获取token和view属性的JS代码之前;其中的data-app配置信息需联系风控方申请后填充。

    注意: 为了方便采集用户对页面的操作行为,如:点击、触摸等,活动页面中的关键元素需指定id 属性,且id 属性的取值需全局唯一。

    安装示例

    <!DOCTYPE HTML>
    <html>
    <head>
      <title>活动页标题</title>
      <meta name="Keywords" content="">
      <meta name="Description" content="">
    </head>
    <body>
    <!-- 您网站的页面代码 -->
    <!-- 您的网站JS代码: 【不会用到ZID】-->
    <!-- 您网站的页面代码 -->
    
    <!-- 引入JSSDK, data-app参数联系风控团队颁发后填充!! -->
    <script data-app=" eyJhcHBfa2V5IjoiNzY1NDMiLCJhcHBfdmlldyI6InByb21vdGUiLCJmb3JtX2Rlc2MiOiIiLCJzZW5kX2ludGVydmFsIjo1MCwic2VuZF9tZXRob2QiOjMsImJyb3dzZXJfdXJsIjoiaHR0cDovL2JqeXotc2FmZS1uZ3gwMS5ianl6LmJhaWR1LmNvbTo4ODc1L2RhdGEvdWEvYWIuanNvbiJ9" src="//sofire.bdstatic.com/js/xaf.js"></script>
    <script type="text/javascript">
    // JSSDK加载后立即初始化,调用初始化接口,参考下文“获取ZID接口>输入参数”
    try {
    var dictParam = {
    "c": "CUIDSTRING", // 业务方通过方法获取的百度CUID
    // 示例:76D6B3976D213912F30C589C7E64C1B2
    "a": "UID",         // Passuid/账户ID,业务方通过方法获取
    "aid": "AID",       // 申请接入后,风控平台颁发的活动ID
    
    "ak": "渠道号", // 调用方渠道号(安全实验室分配,app key)
    "app": "APP类型",   // APP类型:iOS/Android/universe
    "ver": "APP版本号", // 业务方APP版本号,例如“9.1”, “10.1”
    "vc": "APP数字版本号", // Version Code,APP数字版本号(iOS平台为空)
    };
    
    xaf.init(dictParam);
    } catch (e) {}
    
    </script>
    <!-- 您的网站JS代码-->
    <script type="text/javascript">
    // 通过JSSDK接口获取ZID, 随活动数据一起提交到服务器
    var z = "";
    try {
    var as = {
    "o": "task", // 值由活动方定义,
    // 例如活动的不同操作步骤、活动中不同环节等
            "ev": "11",  // 业务自定义操作
    };
    z = xaf.hgz(as);
    } catch (e) {}
    
    //获取 Token的和View的值,随活动数据一起提交到服务器
    var to = "";
    var vw = "";
    try {
    to = xaf.getData().Token;
    vw = xaf.getData().view;
    } catch (e) {}
    </script>
    <!-- 您网站的页面代码 -->
    </body>
    </html>

    注意事项

    • 代码的安装位置要正确。
    • 不要对代码有任何编辑操作,随意编辑代码会导致代码无法成功执行,且可能影响到网站页面的显示。

    初始化JS SDK

    调用JS SDK提供的init接口进行初始化,见[JS SDK初始化接口](#JS SDK初始化接口)。代码示例见初始化示例

    注意: 需要在调用hgz()接口之前完成JSSDK初始化。

    获取JS风控参数值

    活动页面可以分为包含表单和不包含表单两种类型,分别按照下面说明来获取to和vw的值。

    注意1: 使用表单方式时,需要保证表单input标签name和id属性使用约定的名称且全局唯一。

    注意2: token的值包含$、字母和数字示例如下:20$765421523799064802982774354531523799065260212214bae8fd527543063ecd638057566c472a06faa9b4ef3392f0952022ff76f5333b3d2cad1523694353037

    注意3: View的值如包含特殊字符JSSDK会进行URL编码。

    含有表单

    含有表单的活动页面(如登录、注册、提交活动等操作),需在表单提交字段中加入 token 和 view。JSSDK会对表单中的 token 和 view 字段进行赋值,以便这两个参数能在表单提交时一起上报到接入方服务器。

    表单字段名称约定如下:

    <input type="hidden" id="afs_token" name="afs_token">
    <input type="hidden" id="afs_scene" name="afs_scene">

    注意: 活动方服务端提取afs_token和afs_scene的值,用于昊天镜风控系统API的to和vw参数。

    不含表单

    对于不包含表单的活动页面,可使用下面接口获取token 和 view,并随活动数据一起上传至接入方服务。

    //获取 Token的值
    xaf.getData().Token;
    //获取View的值
    xaf.getData().view;

    注意: 活动方服务端从上报数据中提取对应的值,用于昊天镜风控系统API的to和vw参数。

    JS SDK初始化接口

    初始化接口为xaf.init()

    输入参数

    参数为字典类型,包括如下字段:【无法获取的非必选字段可用空值“”】

    字段 类型 必选 说明 用途
    c String Yes H5页面获取的CUID 用于关联校验
    a String Yes H5页面获取的BaiduID 用于关联校验
    aid String Yes 活动ID(风控平台发布) 用于关联校验
    app String No APP类型/客户端:
    ios/Android/universe
    用于关联校验
    ver String No APP版本号 用于关联校验
    vc String No Version Code,APP数字版本号
    Android必选,iOS平台置空
    用于关联校验
    ak String No 调用方APP渠道号(风控平台发布) 用于关联校验

    输出

    布尔类型:

    说明
    true 参数正确,字段c、a、aid不为空
    false 参数格式错误,c、a、aid字段不存在或为空

    初始化示例

    var dictParam = {
    "c": "CUIDSTRING", // 业务方通过方法获取的百度CUID
    // 示例:76D6B3976D213912F30C589C7E64C1B2
    "a": "UID",         // Passuid/账户ID,业务方通过方法获取
    "aid": "AID",       // 申请接入后,风控平台颁发的活动ID
    
    "ak": "渠道号", // 调用方渠道号(安全实验室分配,app key)
    "app": "APP类型",   // APP类型:iOS/Android/universe
    "ver": "APP版本号", // 业务方APP版本号,例如“9.1”, “10.1”
    "vc": "APP数字版本号", // Version Code,APP数字版本号(iOS平台为空)
    };
    
    // 异常处理略
    xaf.init(dictParam);

    获取ZID接口

    需要在完成JS SDK初始化后, 调用 hgz() 接口获取安全SDK的ZID:

    注意: 活动方JS代码中需要用到ZID时(特别切换活动场景时),都应调用该接口重新获取ZID,不能使用缓存!!

    因为hgzAs是调用端能力获取ZID,有可能失败,集成方在活动页面实现重试逻辑。

    为了兼容老版本的APP,活动页面可选择下面一种策略:

    • 先调用hgzAs获取zid,失败后(超时或获取到空值)再使用原方法获取zid
    • 可先使用原有方法获取ZID,再调用hgzAs获取zid。当hgzAs获取到有效ZID,再覆盖原有方法获取到的ZID值

    异步接口hgzAs

    建议使用异步接口。使用同步接口需要端能力支持。

    输入参数

    步获取ZID接口hgzAs有两个参数:

    参数 类型 必选 说明 用途
    Params 字典类型 Yes 输入活动场景等参数 用于关联校验
    Callback 函数 Yes 如果传入了该参数,则使用异步方式获取ZID;否则使用同步方式获取ZID,接口返回值见输出说明 回传ZID

    其中Params参数字段定义:

    字段 类型 必选 说明 用途
    o String Yes 活动操作含义:活动方定义,例如活动的不同操作步骤、活动中不同环节等 用于关联校验
    ev String Yes 事件类型(必选),预先分配事件ID定义:
    1:点击活动按钮(或者活动操作),活动相关操作默认选择此事件
    2:进入活动页面
    3:注册
    4:登录
    5:分享
    6:点赞
    7:评论
    8:提现
    9:下单/提单
    10:支付
    11:业务自定义动作
    用于关联校验
    c String 调用xaf.init接口时,未能从端能力获取到对应值, 调用hgzAs接口时补上该字段值。如果调用init时已经传递该字段值,不需重复传 补充init接口参数中的c字段
    a String 用法同上
    app String 用法同上
    ver String 用法同上
    vc String 用法同上
    ak String 用法同上

    输出

    异步接口不直接输出值,通过回调函数传递ZID。

    异部接口示例

    var z = "";
    try {
      var extParams = {
      "o": "task", // 值由活动方定义,
                   // 例如活动的不同操作步骤、活动中不同环节等”
      "ev": "11",  // 业务自定义操作
    };
       xaf.hgzAs(extParams, function(v) {
    // v 为返回的 ZID
    z = v;
    });
    } catch (e) {}

    ZID用途

    ZID是昊天镜风控系统API的必选参数。需要和to、vw以及活动数据一起上传到业务服务器。

    H5获取ZID的流程

    注意: Wrapper是由APP内部实现,通过JS Bridge技术“封装”安全SDK获取ZID接口的组件。

    同步接口hgz

    注意: 同步接口需要端能力支持。

    输入参数

    参数 类型 必选 说明 用途
    Params 字典类型 Yes 输入活动场景等参数 用于关联校验

    其中Params参数字段定义:

    字段 类型 必选 说明 用途
    o String Yes 活动操作含义:活动方定义,例如活动的不同操作步骤、活动中不同环节等 用于关联校验
    ev String Yes 事件类型(必选),预先分配事件ID定义:
    1:点击活动按钮(或者活动操作),活动相关操作默认选择此事件
    2:进入活动页面
    3:注册
    4:登录
    5:分享
    6:点赞
    7:评论
    8:提现
    9:下单/提单
    10:支付
    11:业务自定义动作
    用于关联校验
    c String 调用xaf.init接口时,未能从端能力获取到对应值, 调用hgzAs接口时补上该字段值。如果调用init时已经传递该字段值,不需重复传 补充init接口参数中的c字段
    a String 用法同上
    app String 用法同上
    ver String 用法同上
    vc String 用法同上
    ak String 用法同上

    hgz输出

    同步接口直接返回string类型的ZID值。

    同步接口示例

    var z = "";
    try {
    var extParams = {
    "o": "task", // 值由活动方定义,
                // 例如活动的不同操作步骤、活动中不同环节等”
        "ev": "11",  // 业务自定义操作
    };
    z = xaf.hgz(extParams);
    } catch (e) {}
    上一篇
    Android安全SDK文档
    下一篇
    名词解释