微信小程序提供两种对接方式:插件化对接与sdk对接,请根据下方的对比选择合适的对接方式接入
插件化与sdk对接方式对比:
- 插件化代码不直接提供sdk代码,申请通过即可使用
- 插件发布新版本后,小程序管理者会收到更新通知,可体验新版插件并更新发布小程序,小程序发布不需再审核
- 小程序可以调用插件,插件不能再调用其他插件
- 普通分包中仅能在一个分包内使用插件、同一个插件不能被多个分包同时引用,独立分包中暂时不支持使用插件
1.插件版 SDK
1.1 小程序管理后台添加插件
- 登录微信公众平台,点击左侧下方设置菜单
- 进入设置页面,点击第三方设置标签页
- 在插件管理模块中,点击添加插件按钮
- 搜索 wxfp ,选择插件,然后完成添加(申请之后,管理员会在第二天收到使用申请,若较紧急,可联系开发人员快速通过审批)
1.2 小程序代码集成
1.小程序 app.json
里声明插件
{
"plugins": {
"tdfp-plugin": {
"version": "1.8.5",
"provider": "wxc3b909c3d24c5417"
}
},
}
- 注意 :三方框架可对应添加。如
uni-app
,可在manifest.json
文件的mp-weixin
模块中添加上述声明
2.引用插件 &&必要的配置
在 app.js
中partnerCode
为必要参数,appname
和channel
为可选字段:
const plugin = requirePlugin('tdfp-plugin')
App({
......
globalData: {
......
_fmOpt: {
partnerCode: "", // 请填入您的partner code
appName: "", // 请填入您的app name 同一个公司的不同小程序请填入不同的AppName
channel: "", // 请填入您的channel
env: "PRODUCTION"
}
},
onLaunch(){
let fmagent = new plugin.FMAgent(this.globalData._fmOpt)
fmagent.init()
}
......
})
3.获取 blackBox
设备指纹 SDK 采用类微信 API 的调用模式,支持传入 success
、fail
、complete
三个回调及其它配置字段:
const plugin = requirePlugin('tdfp-plugin')
var that = this
var fmagent = new plugin.FMAgent(app.globalData._fmOpt)
fmagent.getInfo({
page: that, // 请传入 FMAgent 所在的 Page 或 Component 对象
mode:'plugin',
openid: '', // 如果 openid 或者 unionid 为空或者 undefined,请勿加密上传,传空字符串即可
// 如果您开通了 unionid 功能,请传入加密的用户 unionid,
// 请传入加密的用户 openid(需保证加密后的 openid 与原始 openid 是一一对应关系)
unionid: '',
success: function (res) {},// 成功回调,res 为 blackBox 字符串
fail: function (res) {},// 失败回调,res 为各种 exception 对象
complete: function (res) {} // 完成回调,res为blackbox字符串或者exception 对象
})
2. 标准版 SDK
2.1 添加同盾域名
小程序对各种请求接口都做了域名限制,所以需要在小程序网站后台页面中添加同盾域名才可以保证小程序能正常给同盾设备指纹服务器发送信息
在 设置
-开发设置
-服务器域名
的 request 合法域名
中添加:
环境 | 域名 |
---|---|
国内生产环境(必须) | https://fp.tongdun.net |
注意:
- 如果是从 1.6.1 以下的版本升级到最新,因为小程序存在缓存,请注意添加新老 2 个域名,老域名:https://fp.fraudmetrix.cn 新域名:https://fp.tongdun.net
- 如果线上版本小程序仅会访问同盾生产环境,那么添加第一个生产域名即可
2.2 插入 canvas 节点
同盾小程序设备指纹中使用了 canvas 指纹技术,由于目前微信的限制,我们无法通过 JS 来动态创建 DOM 节点,所以需要在集成时手动加入。假设我们想在 index
页面中采集设备信息,那么就需要在 pages/index/index.wxml
文件末尾添加以下代码:
<view>
<canvas canvas-id='tdcanvas' style="visibility: hidden;position: fixed;z-index: -999;left: 9999px;"></canvas>
</view>
注意:
- 样式文件让设备指纹 SDK 立即隐藏这个节点,SDK 会在用户感知不到的时间内完成采集
- 请勿修改
canvas-id
,修改会导致 SDK 无法正常工作
2.3 引用 SDK && 必要的配置
在需要设备指纹的页面引入SDK,比如:在 pages/index/index.js
中,先在文件顶部引用 SDK 文件:
import FMAgent from '../../fmsdk/fm-xxx-es.min.js'
配置
partnerCode
和 appName
为必要参数,如果没有传入则初始化时会抛出异常
在 app.js
中:
App({
......
globalData: {
......
_fmOpt: {
partnerCode: "", // 请填入您的 partner code
appName: "", // 请填入您的 app name
env: "PRODUCTION"
}
}
})
2.4 获取blackbox
我们的设备指纹 SDK 采用类微信 API 的异步调用模式,支持传入 success
、fail
、complete
三个回调及其它配置字段:
var that = this
var fmagent = new FMAgent(app.globalData._fmOpt) // 这里需要传入一些必要配置
fmagent.getInfo({
page: that, // 请传入 FMAgent 所在的 Page 或 Component 对象
openid: '', // 请传入加密的用户 openid
// 如果您开通了 unionid 功能,请传入加密的用户 unionid
// 否则留空即可
unionid: '',
success: function (res) {
// 成功回调,res 为 blackBox 字符串
},
fail: function (res) {
// 失败回调,res 为各种 exception 对象
},
complete: function (res) {
// 完成回调,res 为各种blackBox字符串或者exception 对象
}
})
设备指纹参数说明
参数 | 类型 | 描述 | 示例 | 是否必传 | 是否移除 |
---|---|---|---|---|---|
page | Object | 当前所在的page对象或component对象 | that | 是 | |
openid | string | 加密后的用户openid(加密算法可以随意选择,请确保加密前后的一一对应关系,我们建议使用MD5或者SHA256)(切记不可以传自定义默认值,没有值请传空字符串,否则会导致碰撞) | ef54040ea9cb599823077 | 是 | |
mode | string | 当前对接模式(插件化接入请传入'plugin',sdk接入方式请忽略) | 'plugin' | 否 | |
unionid | string | 加密后的用户unionid(加密算法可以随意选择,请确保加密前后的一一对应关系,我们建议使用MD5或者SHA256)(切记不可以传自定义默认值,没有值请传空字符串,否则会导致碰撞) | ef54040ea9cb599823077 | 否 | |
getInfoType | string | 获取blackbox的模式('1':优先使用缓存的blackbox,'2':优先使用实时采集的blackbox,'3':优先使用未过期的blackbox至过期,默认模式为'1') | '1' | 否 | |
timeout | Integer | 获取blackbox超时(默认2500,包括采集和发送请求的总时长,范围:2500-16000,单位ms) | 6000 | 否 | |
getLocationAllowed | boolean | 是否采集位置信息。如需采集位置信息,请联系运营获取隐私合规指导(默认false不采集,如需采集请提前获取微信及小程序的位置信息授权,且配置当前项为true) | 否 | latitude、longitude | |
noClipboard | boolean | 是否不采集剪切板(部分手机会有系统提示采集了剪切板,有剪切板可部分增强我们的恢复能力)默认true不采集 | false | 否 | clipoard |
success | function | 获取成功回调 | function(res) {/返回值为string类型,即black_box的值 /} | 是 | |
fail | function | 获取失败回调 | function(res) {/失败回调,res 为各种 exception 对象 /} | 是 | |
complete | function | 获取完成回调 | function(res) {/返回值为string类型或者各种 exception 对象,即black_box的值 /} | 否 |
注意:
- blackbox存在有效期,所以请不要自行对blackbox做缓存,在我们SDK内部有缓存机制,所以请在需要blackbox的地方,调用getInfo接口即可
- 降级blackbox的长度在3000-5000字节,建议上报blackbox放在body中