Uniapp

支持平台：App（Android / iOS / Harmony）、H5 / Web、微信小程序、支付宝小程序、字节小程序、百度小程序、京东小程序、小红书小程序。

所有端对外暴露统一 API，业务代码无需关心底层平台差异。

1. 插件安装与配置#

1.1 复制 `TrustDevice/` 目录#

将 TrustDevice/ 整个目录复制到项目根目录：

TEXT

your_project/
└── TrustDevice/                      ← 整个目录拖入项目即可
    ├── index.js                      ← 统一入口，所有端只 import 这一个文件
    ├── components/
    │   └── td-canvas.vue             ← 隐藏 canvas 组件（字节/百度/京东端必须引入）
    └── fmsdk/
        ├── fm-tt-xxx-es.saas.js      ← 字节小程序 SDK（字节端必须）
        ├── fm-bd-xxx-es.min.js       ← 百度小程序 SDK（百度端必须）
        ├── fm-jd-xxx-es.min.js       ← 京东小程序 SDK（京东端必须）
        └── fm-xhs-xxx-es.min.js      ← 小红书小程序 SDK（小红书端必须）

1.2 原生插件包（仅 App 端需要）#

在 DCloud 插件市场下载 TrustDeviceUniPlugin 插件。
将 TrustDecision-TrustDeviceUniPlugin 文件夹放入 your_project/nativeplugins 目录。
在 HBuilderX 中选中 manifest.json，进入「App 原生插件配置」。
点击「本地插件」->「选择本地插件」，勾选 TrustDeviceUniPlugin。

TEXT

your_project/
└── nativeplugins/
    └── TrustDecision-TrustDeviceUniPlugin/
        ├── android/                  ← AAR 文件
        ├── ios/                      ← xcframework 文件
        └── package.json

2. 统一 API 说明#

方法	说明	支持端
`TrustDevice.init(options)`	初始化 SDK，应在用户同意隐私协议后调用	全端
`TrustDevice.getBlackBox(options?)`	同步获取 blackbox	App（真同步）、微信（getInfoSync）、H5（返回缓存值）；其他端返回空字符串
`TrustDevice.getBlackBoxAsync(options)`	异步回调方式获取 blackbox	全端
`TrustDevice.getBlackBoxPromise(options?)`	Promise 方式获取 blackbox，可 `await`	全端
`TrustDevice.initPage()`	页面级初始化，在需要采集的页面 `onLoad` 中调用	字节 / 百度 / 京东 / 小红书
`TrustDevice.getSDKVersion()`	获取原生 SDK 版本号	App

3. App（Android / iOS）集成配置#

在 manifest.json 的 app-plus.distribute.android.permissions 中声明：

JSON

"<uses-permission android:name=\"android.permission.INTERNET\"/>",
"<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/>",
"<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\"/>",
 
// 可选权限（不声明将放弃部分设备信息采集）
"<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/>",
"<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
"<uses-permission android:name=\"android.permission.READ_PHONE_STATE\"/>",

4. 小程序集成配置#

4.1 微信小程序后台添加插件#

登录微信公众平台：

TEXT

设置 -> 第三方设置 -> 插件管理 -> 添加插件

搜索 wxfp 完成添加。

4.2 支付宝小程序后台添加插件#

登录支付宝小程序后台，添加设备指纹插件。

插件 appId：

TEXT

2021003160688029

4.3 字节小程序后台添加域名#

在字节小程序后台添加 request 合法域名：

4.4 百度小程序后台添加域名#

在百度小程序后台添加 request 合法域名：

4.5 京东小程序后台添加域名#

在京东小程序后台添加 request 合法域名：

4.6 Uniapp 项目 `manifest.json` 配置#

JSON

"mp-weixin": {
  "appid": "你的小程序 appid",
  "plugins": {
    "tdfp-plugin": {
      "version": "2.1.5",
      "provider": "wxc3b909c3d24c5417"
    }
  }
},
"mp-alipay": {
  "plugins": {
    "tdfp-plugin": {
      "version": "*",
      "provider": "2021003160688029"
    }
  }
}

5. 最佳实践#

5.1 初始化#

各端参数通过平台子对象传入。partner 全端共用，只填自己需要的平台即可：

JavaScript

import TrustDevice from "@/TrustDevice/index.js";
 
// App.vue onLaunch，用户同意隐私协议后调用
TrustDevice.init({
  partner: "your_partner", // 必填，全端共用
 
  android: {
    // Android APP
    appKey: "android_appkey",
    channel: "your_app_channel",
    dataCenter: "cn", // cn/sg/us/fra/idna
  },
 
  ios: {

5.2 页面级注册（采集页面，小程序必须）#

VUE

<template>
  <view>
    <td-canvas />
    <!-- 其他内容 -->
  </view>
</template>
 
<script>
import TrustDevice from "@/TrustDevice/index.js";
import TdCanvas from "@/TrustDevice/components/td-canvas.vue";
 
export default {
  components: { TdCanvas },
  onLoad() {

5.3 在业务节点获取 blackbox#

异步回调（推荐）#

JavaScript

TrustDevice.getBlackBoxAsync({
  openid: "", // 加密后的 openid（建议提供，没有传空字符串）
  unionid: "", // 加密后的 unionid（建议提供，没有传空字符串）
  success(blackbox) {
    submitForm({ blackbox });
  },
  fail(err) {
    console.error("获取 blackbox 失败", err);
  },
});

Promise / await（async 函数内）#

JavaScript

const blackbox = await TrustDevice.getBlackBoxPromise({
  openid: "",
  unionid: "",
});
submitForm({ blackbox });

同步（App 端、H5、微信小程序支持，其他端可能返回空）#

JavaScript

const blackbox = TrustDevice.getBlackBox({
  openid: "",
  unionid: "",
});

6. `init` 配置项说明#

支持端：

TEXT

android / ios / harmony / web / mp-weixin / mp-alipay / mp-toutiao / mp-baidu / mp-jd / mp-xhs

参数	类型	必填	说明
`partner`	string	是	合作方编码，全端顶层字段，请联系运营获取
`appKey`	string	是	应用标识，android / ios / harmony 各不同，参考获取 appKey
`dataCenter`	string	是	部署区域：`cn` / `sg` / `us` / `fra` / `idna`（App 端）
`h5fmUrl`	string	否	H5 SDK 脚本地址，联系运营获取（web 端必填, baseUrl）
`channel`	string	否	渠道标识
`appName`	string	否	应用名称，同一公司不同应用填不同值
`debug`	boolean	否	反调试，默认关闭；开发阶段建议开启，发布时关闭（android / ios）
`timeLimit`	number	否	网络请求超时秒数，默认 15（android / ios）
`location`	boolean	否	是否采集地理位置信息，默认 `true`（android / ios）
`collectLevel`	string	否	降级 blackbox 裁剪长度，`'M'` 约 2000 字符，默认 5000 字符（android / ios）
`IDFA`	boolean	否	是否采集广告标识符，默认 `true`（ios）
`deviceName`	boolean	否	是否采集设备名称，默认 `true`（ios）
`runningTasks`	boolean	否	是否获取正在运行的任务，默认 `true`（android）
`sensor`	boolean	否	是否采集传感器信息，默认 `true`（android）
`readPhone`	boolean	否	是否采集 `READ_PHONE_STATE` 权限相关信息，默认 `true`（android）
`installPackageList`	boolean	否	是否采集安装包列表，默认 `true`（android）
`wifiMac`	boolean	否	是否采集 WIFI MAC 地址，默认 `false`（android）

7. `getBlackBoxAsync` 参数说明#

字段	类型	说明	支持端
`page`	Object	当前页面或组件对象，不传则自动取栈顶页面	各小程序端
`openid`	string	加密后的用户 openid（没有传空字符串，不可传自定义默认值）	微信 / 支付宝 / 百度 / 小红书
`unionid`	string	加密后的用户 unionid（没有传空字符串）	微信 / 支付宝 / 字节 / 百度 / 京东
`getInfoType`	string	`'1'` 缓存优先（默认）/ `'2'` 实时采集 / `'3'` 未过期优先	各小程序端
`timeout`	number	超时 ms，小程序端范围 2500-16000，默认 2500	各小程序端
`noClipboard`	boolean	是否不采集剪切板，默认 `true` 不采集	微信 / 字节
`getLocationAllowed`	boolean	是否采集位置信息，默认 `false`，需提前获取授权	微信
`success`	Function	成功回调，参数为 blackbox 字符串	全端
`fail`	Function	失败回调，参数为错误对象 `{ code, msg }`	全端
`complete`	Function	完成回调，无论成败均触发	全端

8. 鸿蒙 Harmony 集成指导#

仅使用 Uni 构建 Harmony 应用的场景，可参考本集成方案。

TrustDevice插件里包含 harmony-configs 参考配置。

8.1 添加 SDK dependencies#

在 harmony-configs/oh-package.json5 添加 dependencies：

JSON5

"@trustdecision/mobrisk": "latest"

8.2 新增桥接注册文件#

将两个 .ets 文件放入 harmony-configs/entry/src/main/ets/：

TrustDevicePlugin.ets（SDK 桥接层，与本项目同名文件完全一致）
MyAbilityStage.ets（注册模块、注入 context）

如果用户项目已有自己的 AbilityStage，则不需要 MyAbilityStage.ets，只需把以下两行合并到已有的 onCreate() 中：

JavaScript

TrustDevicePlugin.setContext(this.context)
registerModule('TrustDecision-MobRisk', TrustDevicePlugin as ESObject)

8.3 `module.json5`#

在 module 根层添加 srcEntry（若已有 AbilityStage 则跳过）：

JSON5

"srcEntry": "./ets/MyAbilityStage.ets"

在 requestPermissions 数组里追加以下权限（已有的不用重复）：

JSON5

{ "name": "ohos.permission.INTERNET" },
{ "name": "ohos.permission.GET_NETWORK_INFO" },
{ "name": "ohos.permission.GET_WIFI_INFO" },
{ "name": "ohos.permission.STORE_PERSISTENT_DATA" },
{
  "name": "ohos.permission.APPROXIMATELY_LOCATION",
  "reason": "$string:location_reason",
  "usedScene": {
    "abilities": ["EntryAbility"],
    "when": "inuse"
  }

8.4 添加权限说明文案#

文件路径：

TEXT

harmony-configs/entry/src/main/resources/base/element/string.json

在已有的 string 数组里追加一条：

JSON

{
  "name": "location_reason",
  "value": "用于采集设备位置信息以提升风险识别能力"
}

如果该文件不存在，新建并写入本项目的同名文件内容即可。

8.5 注意事项#

不要自行缓存 blackbox，SDK 内部有缓存机制，每次调用 getBlackBoxAsync 即可。
blackbox 存在有效期，请在业务提交时实时获取。
提交 blackbox 时使用表单 body 提交，避免 URL encode 导致数据异常。
正常 blackbox 长度约 26 位；若返回 3000-5000 字符的降级 blackbox，表明当前采集异常（超时或网络抖动），属正常现象。

Uniapp

1. 插件安装与配置#

1.1 复制 TrustDevice/ 目录#

1.2 原生插件包（仅 App 端需要）#

2. 统一 API 说明#

3. App（Android / iOS）集成配置#

4. 小程序集成配置#

4.1 微信小程序后台添加插件#

4.2 支付宝小程序后台添加插件#

4.3 字节小程序后台添加域名#

4.4 百度小程序后台添加域名#

4.5 京东小程序后台添加域名#

4.6 Uniapp 项目 manifest.json 配置#

5. 最佳实践#

5.1 初始化#

5.2 页面级注册（采集页面，小程序必须）#

5.3 在业务节点获取 blackbox#

异步回调（推荐）#

Promise / await（async 函数内）#

同步（App 端、H5、微信小程序支持，其他端可能返回空）#

6. init 配置项说明#

7. getBlackBoxAsync 参数说明#

8. 鸿蒙 Harmony 集成指导#

8.1 添加 SDK dependencies#

8.2 新增桥接注册文件#

8.3 module.json5#

8.4 添加权限说明文案#

8.5 注意事项#

1. 插件安装与配置#

1.1 复制 TrustDevice/ 目录#

1.2 原生插件包（仅 App 端需要）#

2. 统一 API 说明#

3. App（Android / iOS）集成配置#

4. 小程序集成配置#

4.1 微信小程序后台添加插件#

4.2 支付宝小程序后台添加插件#

4.3 字节小程序后台添加域名#

4.4 百度小程序后台添加域名#

4.5 京东小程序后台添加域名#

4.6 Uniapp 项目 manifest.json 配置#

5. 最佳实践#

5.1 初始化#

5.2 页面级注册（采集页面，小程序必须）#

5.3 在业务节点获取 blackbox#

异步回调（推荐）#

Promise / await（async 函数内）#

同步（App 端、H5、微信小程序支持，其他端可能返回空）#

6. init 配置项说明#

7. getBlackBoxAsync 参数说明#

8. 鸿蒙 Harmony 集成指导#

8.1 添加 SDK dependencies#

8.2 新增桥接注册文件#

8.3 module.json5#

8.4 添加权限说明文案#

8.5 注意事项#

1.1 复制 `TrustDevice/` 目录#

4.6 Uniapp 项目 `manifest.json` 配置#

6. `init` 配置项说明#

7. `getBlackBoxAsync` 参数说明#

8.3 `module.json5`#

1.1 复制 `TrustDevice/` 目录#

4.6 Uniapp 项目 `manifest.json` 配置#

6. `init` 配置项说明#

7. `getBlackBoxAsync` 参数说明#

8.3 `module.json5`#