JavaScript安全SDK文档
所有文档

          业务安全风控 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. (集成安全SDK后请关注)调用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 = {
          "a": "UID",         // 账户ID,业务方脱敏处理后的账号id
          "aid": "AID",       // 申请接入后,风控平台颁发的活动ID
          "app": "APP类型",   // APP类型:iOS/Android/universe
          };
          
          xaf.init(dictParam);
          } catch (e) {}
          
          </script>
          <!-- 您的网站JS代码-->
          <script type="text/javascript">
          // 通过JSSDK接口获取ZID, 随活动数据一起提交到服务器
          var z = "";
          try {
          var as = {
          "o": "task", // 值由活动方定义,
          // 例如活动的不同操作步骤、活动中不同环节等
                  "ev": "11",  // 业务自定义操作
          };
          z = xaf.hgzAs(as,callback);
          } 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()

          输入参数

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

          字段 类型 必选 说明 用途
          a String NO 业务方脱敏处理后的账号id 用于关联校验
          aid String Yes 活动ID(风控平台发布) 用于关联校验
          app String No APP类型/客户端:
          ios/Android/universe
          用于关联校验

          输出

          布尔类型:

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

          初始化示例

          var dictParam = {
          
          "a": "UID",         // 业务方脱敏处理后的账号id ——可选
          "aid": "AID",       // 申请接入后,风控平台颁发的活动ID  ——必选
          "app": "APP类型",   // APP类型:iOS/Android/universe ——可选
          };
          
          // 异常处理略
          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

          建议使用异步接口。使用同步接口需要端能力支持。(未集成安全SDK不需要关注此项)

          输入参数

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

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

          其中Params参数字段定义:

          字段 类型 必选 说明 用途
          ev String Yes 事件类型(必选),预先分配事件ID定义:
          1:点击活动按钮(或者活动操作),活动相关操作默认选择此事件
          2:进入活动页面
          3:注册
          4:登录
          5:分享
          6:点赞
          7:评论
          8:提现
          9:下单/提单
          10:支付
          11:业务自定义动作
          用于关联校验
          a String 用法同上
          app 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接口的组件。

          上一篇
          Android安全SDK文档
          下一篇
          名词解释