文档简介：
本 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="//sofire.bdstatic.com/js/dfxaf.js"></script>
引用 JS 文件时请勿缓存，应尽量遵守昊天镜后端返回的 JS 过期时间。
data-bdms-faccdee21b68属性的PARAMETERS值请采用『data-app』参数的值，获取方法见本文『前置说明』一节，请注意完整复制该参数。
请将 JS SDK 安装在标签</ body >标记之前。如示例（注意不要忘了data-bdms-faccdee21b68字符串结尾的等号）：
<!DOCTYPE HTML> <html> <head> <title>活动页标题</title> <meta name=”Keywor
ds” content=””> <meta name=”Description” content=””> </head> <body> <!-
- 您网站的页面代码 --> <!-- 您的网站 JS 代码 --> <!-- 引入 JS SDK，填充 data-bdms-faccdee21b68
参数 --> <script data-bdms-faccdee21b68="eyJhcHBfa2V5IjoiNzY1NDMiLCJhcHBfdmlldyI6InByb2
1vdGUiLCJmb3JtX2Rlc2MiOiIiLCJzZW5kX2ludGVydmFsIjoyMCwic2VuZF9tZXRob2QiOjMsImFjdGlvbl91
cmwiOiJodHRwOi8vY3AwMS1jeXJpc2stYWRtaW4uZXBjLmJhaWR1LmNvbTo4ODc1L2RhdGEvdWEvcHVzaGV2Z
W50Lmpzb25wIiwiYnJvd3Nlcl91cmwiOiJodHRwOi8vY3AwMS1jeXJpc2stYWRtaW4uZXBjLmJhaWR1LmNvb
To4ODc1L2RhdGEvdWEvcHVzaHVhLmpzb24ifQ==" src="//sofire.bdstatic.com/js/dfxaf.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 | 尽量提供 |
| 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="eyJhcHBfa2V5IjoiNzY1NDMiLCJhcHBfdmlldyI6InByb21vd
GUiLCJmb3JtX2Rlc2MiOiIiLCJzZW5kX2ludGVydmFsIjoyMCwic2VuZF9tZXRob2QiOjMsImFjdGlvbl91
cmwiOiJodHRwOi8vY3AwMS1jeXJpc2stYWRtaW4uZXBjLmJhaWR1LmNvbTo4ODc1L2RhdGEvdWEvcHVzaGV2
ZW50Lmpzb25wIiwiYnJvd3Nlcl91cmwiOiJodHRwOi8vY3AwMS1jeXJpc2stYWRtaW4uZXBjLmJhaWR1LmN
vbTo4ODc1L2RhdGEvdWEvcHVzaHVhLmpzb24ifQ==" src="//sofire.bdstatic.com/js/dfxaf.js"><
/script> <script> // 完整示例 var biz = { // ID 类字段，由接入方自定义，需要保证前后端完
全一致 "like_id": "99324054", "inviter_id": "54323943", "page_id": "12399" } var dat
a = { "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/s2stCM
d+6smQ10msXY5ZtvtY+Yr+5v3rgspLjRKp9USaeK5NCqGpjYDo9/XjvHgTP43nLdYBeg5ucOQhy3K3WY
1W4+OftFBO7tmZ5CvKWgOloI958+ErXhnLaEBA1fUQaYUoAPAfejtrUgjoEcWvtPJ8dLECMS+RhugMQP
Q3YsDtP7phrdQcADOTqmr7cUVZWeK4+AYBU7CJGhod26jikVjJwnPoett7Br5MNcJCc7Z93KC6/HP12v
VpP8iMD/ktO8ug2+GUbzD80bjLM06Nm2PVGrfZoFSeFmQrpHyes/l9zw/lSCgBX5IUJQ0VDDwFyMa5f7
0jJjfMXaNTvFT9iYB4pGryJnC5s2Nm383dI3npPeUNBgm3rWyyk4AZ5Teza1bSKVPw1SUk0hQ8gg1O2D
i8+NdFyj5tOw91kzc3gS55YkM0vDxm/JMY0GkRQwouj8nObAeL8uYKTSnRQAtoGp24PwKlf3TzUa0Vot
PJHNzE9CXqMIwRTCgpdPt+XhHNHjAa8JDnJnhfiruQkYdN1/|ra0gZdNdYLlm+LJ5Z5QkCD4Fu9dbvee
IUpnbVqdeQmc=|10|3f9d3cef5028e6ea5b3df9dae57dacde" }
错误返回示例（此时也应上报返回的 jt 参数）
{ "code": 1, "msg": "获取token出错", "jt": "CODED--v30OUi3RL_;U`_1ZQOCj)l-mG_LeA
cAiE08M)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 字段
- 对于仅验证风控 JS SDK 的 jt 参数的请求，app 字段必须填写为 universe（小写）
- 如果接入风控 JS SDK 时前端可以获取到 zid 参数，则需要同时到昊天镜接口验证 jt / z (zid) 参数。对于同时验证这2个参数的请求，app 字段应以移动端的实际操作系统为准，可选值包括：ios/android（小写）
- userAgent
- jt / z 参数均不应缓存
-
biz 参数（位于 extra 字段），格式为 Map[String, String]
- biz 表示同 jt 绑定的业务数据，jt 参数仅可用于此业务数据对应场景。需要前后端均将相应的业务数据 (biz) 传递给昊天镜以判断 jt/biz 是否被滥用，前后端必须保证传递的业务数据 (biz) 完全一致，否则可能会被判断为非法请求。
- 后端传递 biz 的方式是将 biz 参数放在 extra 字段，见下例
# body 实例，自：『百度云API SDK接口鉴权』示例代码 body = { # 昊天镜共有字段（后端） # ... #
昊天镜风控 JS 字段（后端） "jt": "OQIYy2JZKNp1pWxiiqA+5pmg5KhWqilergoopg7ZZ/s2stCMd+6smQ10m
sXY5ZtvtY+Yr+5v3rgspLjRKp9USaeK5NCqGpjYDo9/XjvHgTP43nLdYBeg5ucOQhy3K3WY1W4+OftFBO7tmZ5C
vKWgOloI958+ErXhnLaEBA1fUQaYUoAPAfejtrUgjoEcWvtPJ8dLECMS+RhugMQPQ3YsDtP7phrdQcADOTqmr7
cUVZWeK4+AYBU7CJGhod26jikVjJwnPoett7Br5MNcJCc7Z93KC6/HP12vVpP8iMD/ktO8ug2+GUbzD80bjLM0
6Nm2PVGrfZoFSeFmQrpHyes/l9zw/lSCgBX5IUJQ0VDDwFyMa5f70jJjfMXaNTvFT9iYB4pGryJnC5s2Nm383d
I3npPeUNBgm3rWyyk4AZ5Teza1bSKVPw1SUk0hQ8gg1O2Di8+NdFyj5tOw91kzc3gS55YkM0vDxm/JMY0GkRQ
wouj8nObAeL8uYKTSnRQAtoGp24PwKlf3TzUa0VotPJHNzE9CXqMIwRTCgpdPt+XhHNHjAa8JDnJnhfiruQkY
dN1/|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://sofire.bdstatic.com/js/dfxaf.js'？
答：这一错误同 CSP 有关。
CSP (Content Security Policy) 是现代浏览器支持的白名单机制，以增强网页安全性。由开发者告知客户端：哪些外部资源可以加载和执行。
在启用了 CSP 的站点加载昊天镜风控 JS SDK 需要开启以下配置：
Content-Security-Policy: script-src 'self' 'unsafe-inline' https://sofire.bdstatic.com
参考资料：
内容安全策略( CSP ) - HTTP | MDN
