JavaScript安全SDK文档

更新时间：2023-11-02

本 SDK 运行在浏览器环境，支持浏览器如下：

PC 端或移动端的浏览器环境，如：Chrome、Firefox、IE 8+等
App 内嵌入的 Webview

前置说明

必选步骤：接入方需要通过 SDK 获取 jt 参数，并传递给昊天镜后端用于风险验证，对应接入向导中『参数列表』的『入参（JSON格式）』中的 jt 字段。

可选步骤：如果接入方的浏览器为 Webview，且该 Webview 所在的宿主 App 接入了昊天镜安全 SDK（Android / iOS），可以通过本 SDK 调用端能力来获取 zid 参数，此参数对应接入向导中『参数列表』的『入参（JSON格式）』中的 z 字段，为可选参数。若未接入昊天镜安全 SDK，则无法获取此参数。

注意：jt 和 zid 参数均不应缓存，前后端均应以最新获取的为准。

使用服务分为三步：

昊天镜平台提供活动 id（aid）和 data-app 参数

a) 活动 id 由接入方自行新建或复用已有的

b) data-app 参数来自：控制台 → 接入向导 → 端类型选中『WEB/H5/Wap页面』 → 获取JS-SDK data-app
接入方前端接入
接入方后端接入

整体流程

时序图如下：

返回的 Token (jt) 参数有2种：

网络较差时：CODED--v30OUi3RL_;U`_1ZQOCj)l-mG_LeAcAi08M)Pl^\W:a;dv?g@]ez)a=[Ie][AjakTOEW6Q-[<VQ0zpU`4_zJ7v\O/qp@8,PlOLnK)QH;tl`>A[QO4]TK,n1,-r0S4vtOCLnj3f\,?U]c2Y5y5^UWHaY+?fa?2+epOcD3ogsP+krSH
网络良好时（也是绝大多数情况）：OQIYy2JZKNp1pWxiiqA+5pmg5KhWqilergoopg7ZZ/s2stCMd+6smQ10msXY5ZtvtY+Yr+5v3rgspLjRKp9USaeK5NCqGpjYDo9/XjvHgTP43nLdYBeg5ucOQhy3K3WY1W4+OftFBO7tmZ5CvKWgOloI958+ErXhnLaEBA1fUQaYUoAPAfejtrUgjoEcWvtPJ8dLECMS+RhugMQPQ3YsDtP7phrdQcADOTqmr7cUVZWeK4+AYBU7CJGhod26jikVjJwnPoett7Br5MNcJCc7Z93KC6/HP12vVpP8iMD/ktO8ug2+GUbzD80bjLM06Nm2PVGrfZoFSeFmQrpHyes/l9zw/lSCgBX5IUJQ0VDDwFyMa5f70jJjfMXaNTvFT9iYB4pGryJnC5s2Nm383dI3npPeUNBgm3rWyyk4AZ5Teza1bSKVPw1SUk0hQ8gg1O2Di8+NdFyj5tOw91kzc3gS55YkM0vDxm/JMY0GkRQwouj8nObAeL8uYKTSnRQAtoGp24PwKlf3TzUa0VotPJHNzE9CXqMIwRTCgpdPt+XhHNHjAa8JDnJnhfiruQkYdN1/|ra0gZdNdYLlm+LJ5Z5QkCD4Fu9dbveeIUpnbVqdeQmc=|10|3f9d3cef5028e6ea5b3df9dae57dacde

由于 jt 中存在特殊字符，传递参数时建议：

前端采用 encodeURIComponent 函数对其进行编码
后端也应采用同 decodeURIComponent 函数等义的函数进行解码

返回的 zid 参数示例：

iOS 返回值：siZPu9nvA6xPSIMew-C1bBmR49jbayNZBijiG1ZHsj4OkLgoKO46q1DnjUYnZUwTDNkVTrhJw-Pz2FOkFTrfQYw

安卓返回值：RRX5H0V1vO0U7CxWfc51wLBWAoME5FVncVFPBrkxbs2YsxXV0svCPJC4Zwh2cpWQmakUYVJEFQYPTa1dtXNHCZA

前端接入

前端负责加载 JS SDK，并在关键操作时发起主动上报。

初始化

引入方式如下：

<script data-bdms-faccdee21b68="PARAMETERS" src="//safe.cdn.bcebos.com/js/htxaf3.js"></script>

引用 JS 文件时请勿缓存，应尽量遵守昊天镜后端返回的 JS 过期时间。

data-bdms-faccdee21b68属性的PARAMETERS值请采用『data-app』参数的值，获取方法见本文『前置说明』一节，请注意完整复制该参数。

请将 JS SDK 安装在标签</ body >标记之前。如示例（注意不要忘了data-bdms-faccdee21b68字符串结尾的等号）：

<!DOCTYPE HTML>
<html>
<head>
<title>活动页标题</title>
<meta name=”Keywords” content=””>
<meta name=”Description” content=””> </head>
<body>
  <!-- 您网站的页面代码 -->
  <!-- 您的网站 JS 代码 -->
  <!-- 引入 JS SDK，填充 data-bdms-faccdee21b68 参数 -->
  <script data-bdms-faccdee21b68="eyJhcHBfa2V5IjoiNzY1NDMiLCJhcHBfdmlldyI6InByb21vdGUiLCJmb3JtX2Rlc2MiOiIiLCJzZW5kX2ludGVydmFsIjoyMCwic2VuZF9tZXRob2QiOjMsImFjdGlvbl91cmwiOiJodHRwOi8vY3AwMS1jeXJpc2stYWRtaW4uZXBjLmJhaWR1LmNvbTo4ODc1L2RhdGEvdWEvcHVzaGV2ZW50Lmpzb25wIiwiYnJvd3Nlcl91cmwiOiJodHRwOi8vY3AwMS1jeXJpc2stYWRtaW4uZXBjLmJhaWR1LmNvbTo4ODc1L2RhdGEvdWEvcHVzaHVhLmpzb24ifQ==" src="//safe.cdn.bcebos.com/js/htxaf3.js"></script>

加载失败会在控制台抛出相应的异常：

data-bdms-faccdee21b68 解码失败

获取 zid

若接入活动处于 Webview 中，且该 Webview 的宿主 app 接入了昊天镜安全 SDK（Android / iOS），则可以通过端能力获取安全 SDK 的 zid。否则无法获取 zid。

在完成 JS SDK 初始化后，可以调用 hgzAs() 异步接口获取安全 SDK 的 zid：

活动方 JS 代码中需要用到 zid 时(特别是切换活动场景时)，都应调用该接口重新获取 ZID，不可缓存
因为是调用端能力获取 ZID，有失败的可能，接入方要在活动页面实现重试逻辑
若接入的是 PC 端浏览器或者没有端能力的 H5页面，则无法获取 zid。

异步获取 zid 接口 hgzAs 有2个参数：

参数	类型	必选	说明	用途
params	字典类型	是	输入活动场景等参数	用于关联校验
callback	回调函数	是	异步方式获取 zid	获取 zid

其中 params 参数字段定义如下：

字段	类型	必选	说明	用途
aid	String	是	昊天镜分配的活动 id	用于关联校验
ev	String	是	行为操作，用于标识当前调用环节。预先分配操作编码见『附 - ev 可选值列表』	用于关联校验
app	String	否	APP 类型/客户端：ios/android/universe	尽量提供
ver	String	否	APP 版本号	尽量提供

回调函数输出：

参数	类型	说明
zid	String	通过端能力获取的 zid

示例代码如下：

var z = ""; 
try {
  var extParams = {
    "ev": "cash_out", // 业务根据风控场景自定义操作，如 cash_out 标识提现操作
  };
  xaf.hgzAs(extParams, function(v) {
    // v 为返回的 ZID 
    z = v;
  });
} catch (e) {}

关键行为上报

当用户在页面进行关键操作（如：领券、发表回复、点赞等）时，必须先调用 JS SDK 发起主动上报，待上报完成后再执行后续的前端业务逻辑。此上报函数在加载后可视场景多次调用。

调用方式：xaf.report(data)，参数data定义如下：

参数名	参数含义	类型	是否必须	参数说明
aid	AID	String	是	昊天镜平台颁发的活动 ID，若引入时提供了该参数，仍会优先这里提供的参数
complete	上报成功的回调函数	函数	是	函数入参见下，无论上报成功、失败、异常均会触发回调
c	Customer Device ID	String	否	浏览器设备 ID
a	User ID	String	否	用户 ID
ut	User Type	String	否	建议传递接入方特有标识以区分不同用户 ID，如可以传递接入方的二级域名：接入方主站域名为 www.example.com 则可以传递为 example.com
biz	业务数据	Object	否	表示同 jt 绑定的业务数据，jt 参数仅可用于此业务数据对应场景。需要前后端均将相应的业务数据 (biz) 传递给昊天镜以判断 jt/biz 是否被滥用，前后端必须保证传递的业务数据 (biz) 完全一致，否则可能会被判断为非法请求。格式 `Map[String,String]`，可选 key/value 由业务方自定义选择，建议选择有一定区分度的 ID 类字段，样例见下表『业务数据』，。若无也可不设置此参数。

前端传递 biz 的方式是将 biz 值放于 report 函数的 data 参数中。

参数data包含的业务数据biz字段由接入方自定义填写，若无也可不设置。但要注意若使用本字段，则本字段内容需要由接入方前端主动传递给接入方后端，并在接入方后端调用风控后端的验证接口时作为 JSON 结构提供（见 biz 参数）。定义如下：

参数名	参数含义	类型	是否必须	参数说明
like_id	动作对象	String	否	投票场景代表被投票对象；发帖场景代表回帖的原贴；砍价场景代表砍价商品等
inviter_id	邀请人	String	否	邀请人id；师徒邀请、拼团、拆红包、裂变邀请等环节，需要传递此关系
page_id	页面 ID	String	否	页面 ID，如：文章 ID、版面 ID 等
...	...	String	否	其他 Key 可由接入方主动添加，以增强风控效果

调用方式示例：

<script data-bdms-faccdee21b68="eyJhcHBfa2V5IjoiNzY1NDMiLCJhcHBfdmlldyI6InByb21vdGUiLCJmb3JtX2Rlc2MiOiIiLCJzZW5kX2ludGVydmFsIjoyMCwic2VuZF9tZXRob2QiOjMsImFjdGlvbl91cmwiOiJodHRwOi8vY3AwMS1jeXJpc2stYWRtaW4uZXBjLmJhaWR1LmNvbTo4ODc1L2RhdGEvdWEvcHVzaGV2ZW50Lmpzb25wIiwiYnJvd3Nlcl91cmwiOiJodHRwOi8vY3AwMS1jeXJpc2stYWRtaW4uZXBjLmJhaWR1LmNvbTo4ODc1L2RhdGEvdWEvcHVzaHVhLmpzb24ifQ==" src="//safe.cdn.bcebos.com/js/htxaf3.js"></script>
<script>
// 完整示例
var biz = {
  // ID 类字段，由接入方自定义，需要保证前后端完全一致
  "like_id": "99324054",
  "inviter_id": "54323943",
  "page_id": "12399"
}

var data = {
  "c": "4556A06FE971260452B75C51D12DD901",
  "a": "7921493513236",
  "ut": "",
  "aid": "9999",
  "biz": biz,
  "complete": function(data) {
    console.log("jt:", data.jt);
    // 业务逻辑，需要将 data.jt 字段上报至接入方后端
    // submit(..., biz, data.jt)
  }
}

try {
  xaf.report(data)
} catch (error) {
  console.log("error found:", error)
  // 业务逻辑（容错），此时应视 data.jt 为空字符串
}
</script>

回调函数参数

参数名	参数含义	类型	是否必须	参数说明
code	错误码	Int	是	0表示成功，非0为失败
msg	提示信息	String	是	展示错误提示信息
jt	JS Token	String	是	昊天镜产生的 JS Token，需要传递给接入方后端

错误码列表

0 成功
1000 App Key 不存在
1 调用失败

正常返回示例

{
  "code": 0,
  "msg": "",
  "jt": "OQIYy2JZKNp1pWxiiqA+5pmg5KhWqilergoopg7ZZ/s2stCMd+6smQ10msXY5ZtvtY+Yr+5v3rgspLjRKp9USaeK5NCqGpjYDo9/XjvHgTP43nLdYBeg5ucOQhy3K3WY1W4+OftFBO7tmZ5CvKWgOloI958+ErXhnLaEBA1fUQaYUoAPAfejtrUgjoEcWvtPJ8dLECMS+RhugMQPQ3YsDtP7phrdQcADOTqmr7cUVZWeK4+AYBU7CJGhod26jikVjJwnPoett7Br5MNcJCc7Z93KC6/HP12vVpP8iMD/ktO8ug2+GUbzD80bjLM06Nm2PVGrfZoFSeFmQrpHyes/l9zw/lSCgBX5IUJQ0VDDwFyMa5f70jJjfMXaNTvFT9iYB4pGryJnC5s2Nm383dI3npPeUNBgm3rWyyk4AZ5Teza1bSKVPw1SUk0hQ8gg1O2Di8+NdFyj5tOw91kzc3gS55YkM0vDxm/JMY0GkRQwouj8nObAeL8uYKTSnRQAtoGp24PwKlf3TzUa0VotPJHNzE9CXqMIwRTCgpdPt+XhHNHjAa8JDnJnhfiruQkYdN1/|ra0gZdNdYLlm+LJ5Z5QkCD4Fu9dbveeIUpnbVqdeQmc=|10|3f9d3cef5028e6ea5b3df9dae57dacde"
}

错误返回示例（此时也应上报返回的 jt 参数）

{
  "code": 1,
  "msg": "获取token出错",
  "jt": "CODED--v30OUi3RL_;U`_1ZQOCj)l-mG_LeAcAiE08M)Pl^\W:a;dve?g@]ez)a=[Ie][AjakTOEW6Q-[<VQ0zpU`4_zJ7v\O/qp@8,PlOLnK)QH;tl`>A[QO4]TK,n1,-r0S4vtOCLnj3f\,?U]c2Y5y5^UWHaY+?fa?2+epOcD3ogsP+krSH"
}

后端接入

接入方后端需要接收来自接入方前端的 jt / z (zid) 参数并传递给昊天镜接口以验证请求是否合法。其中，jt 参数为字符串（必选），z (zid) 参数为字符串（可选）。

接入方法见：『百度云API SDK接口鉴权』示例代码

除需要按照昊天镜通用方式接入外，对于风控 JS 场景，后端需要注意以下。

app 字段
1. 对于仅验证风控 JS SDK 的 jt 参数的请求，app 字段必须填写为 universe（小写）
2. 如果接入风控 JS SDK 时前端可以获取到 zid 参数，则需要同时到昊天镜接口验证 jt / z (zid) 参数。对于同时验证这2个参数的请求，app 字段应以移动端的实际操作系统为准，可选值包括：ios/android（小写）
userAgent
jt / z 参数均不应缓存
biz 参数（位于 extra 字段），格式为 Map[String, String]
1. biz 表示同 jt 绑定的业务数据，jt 参数仅可用于此业务数据对应场景。需要前后端均将相应的业务数据 (biz) 传递给昊天镜以判断 jt/biz 是否被滥用，前后端必须保证传递的业务数据 (biz) 完全一致，否则可能会被判断为非法请求。
2. 后端传递 biz 的方式是将 biz 参数放在 extra 字段，见下例

# body 实例，自：『百度云API SDK接口鉴权』示例代码
body = {
  # 昊天镜共有字段（后端）
  # ...
  # 昊天镜风控 JS 字段（后端）
  "jt": "OQIYy2JZKNp1pWxiiqA+5pmg5KhWqilergoopg7ZZ/s2stCMd+6smQ10msXY5ZtvtY+Yr+5v3rgspLjRKp9USaeK5NCqGpjYDo9/XjvHgTP43nLdYBeg5ucOQhy3K3WY1W4+OftFBO7tmZ5CvKWgOloI958+ErXhnLaEBA1fUQaYUoAPAfejtrUgjoEcWvtPJ8dLECMS+RhugMQPQ3YsDtP7phrdQcADOTqmr7cUVZWeK4+AYBU7CJGhod26jikVjJwnPoett7Br5MNcJCc7Z93KC6/HP12vVpP8iMD/ktO8ug2+GUbzD80bjLM06Nm2PVGrfZoFSeFmQrpHyes/l9zw/lSCgBX5IUJQ0VDDwFyMa5f70jJjfMXaNTvFT9iYB4pGryJnC5s2Nm383dI3npPeUNBgm3rWyyk4AZ5Teza1bSKVPw1SUk0hQ8gg1O2Di8+NdFyj5tOw91kzc3gS55YkM0vDxm/JMY0GkRQwouj8nObAeL8uYKTSnRQAtoGp24PwKlf3TzUa0VotPJHNzE9CXqMIwRTCgpdPt+XhHNHjAa8JDnJnhfiruQkYdN1/|ra0gZdNdYLlm+LJ5Z5QkCD4Fu9dbveeIUpnbVqdeQmc=|10|3f9d3cef5028e6ea5b3df9dae57dacde",
  "app": "universe",
  "extra": {
    "biz": {
      // ID 类字段，由接入方自定义，需要保证前后端完全一致
      "like_id": "99324054",
      "inviter_id": "54323943",
      "page_id": "12399"
    }
  }
}

附

ev 可选值列表

已有定义如下：

page_enter进入活动页面
register注册
login登录
share分享
like点赞
vote投票
comment评论
cash_out提现
order下单/提单
pay支付
visit浏览
feed浏览feed
red_envelope领取红包
task任务
sign签到
invite邀请
lottery抽奖
reply回帖
bargain砍价

尽可能按照上述约定传递，如上述列表无法满足，可根据当前活动流程，自行设置调用环节编码。

为保证风控服务灵活性，请尽可能详细划分每个调用环节，并将每一个调用环节的编码映射同步风控对接同学。

Q & A

问：为什么会出现 Refused to load the script 'https://safe.cdn.bcebos.com/js/htxaf3.js'？

答：这一错误同 CSP 有关。

CSP (Content Security Policy) 是现代浏览器支持的白名单机制，以增强网页安全性。由开发者告知客户端：哪些外部资源可以加载和执行。

在启用了 CSP 的站点加载昊天镜风控 JS SDK 需要开启以下配置：

Content-Security-Policy: script-src 'self' 'unsafe-inline' https://safe.cdn.bcebos.com

参考资料：

内容安全策略( CSP ) - HTTP | MDN

Android安全SDK文档

名词解释

业务安全风控 AFD