TrustDecision
API Reference
English

Uniapp

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

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

1. 插件安装与配置

下载TrustDevice插件

1.1 复制 TrustDevice/ 目录

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

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 端需要）

  1. 在 DCloud 插件市场 下载 TrustDeviceUniPlugin 插件。
  2. 将 TrustDecision-TrustDeviceUniPlugin 文件夹放入 your_project/nativeplugins 目录。
  3. 在 HBuilderX 中选中 manifest.json，进入「App 原生插件配置」。
  4. 点击「本地插件」->「选择本地插件」，勾选 TrustDeviceUniPlugin。
your_project/
└── nativeplugins/
    └── TrustDecision-TrustDeviceUniPlugin/
        ├── android/                  ← AAR 文件
        ├── ios/                      ← xcframework 文件
        └── package.json

2. 统一 API 说明

方法说明支持端
TrustDevice.init(options)初始化 SDK，应在用户同意隐私协议后调用全端
TrustDevice.getBlackBox(options?)同步获取 blackboxApp（真同步）、微信（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 中声明：

"<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\"/>",
"<uses-permission android:name=\"android.permission.QUERY_ALL_PACKAGES\"/>",

// 如在 Google Play 发布，需添加
"<uses-permission android:name=\"com.google.android.gms.permission.AD_ID\"/>"

4. 小程序集成配置

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

登录 微信公众平台：

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

搜索 wxfp 完成添加。

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

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

插件 appId：

2021003160688029

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

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

设置 -> 开发设置 -> 服务器域名 -> request 合法域名
https://fp.tongdun.net

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

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

管理 -> 基础设置 -> 开发设置 -> 服务器域名 -> request 合法域名
https://cn-fp.apitd.net

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

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

管理 -> 基础设置 -> 开发设置 -> 服务器域名 -> request 合法域名
https://cn-fp.apitd.net

4.6 Uniapp 项目 manifest.json 配置

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

5. 最佳实践

5.1 初始化

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

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: {                         // iOS APP
    appKey: 'ios_appkey',
    channel: 'your_app_channel',
    dataCenter: 'cn'
  },

  web: {                         // H5/Web
    h5fmUrl: 'https://your-fm-url/fm.js'  // 联系运营获取
  },

  'mp-weixin': {                 // 微信小程序
    channel: 'your_app_channel'
  },

  'mp-alipay': {                 // 支付宝小程序
    channel: 'your_app_channel'
  },

  'mp-toutiao': {                // 字节小程序
    channel: 'your_app_channel'
  },

  'mp-baidu': {                  // 百度小程序
    channel: 'your_app_channel'
  },

  'mp-jd': {                     // 京东小程序
    channel: 'your_app_channel'
  },

  'mp-xhs': {                    // 小红书小程序
    channel: ''
  }
})

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

<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() {
    // 确保已执行 TrustDevice.init({ initOptions })
    // 小程序类 Page 初始化
    TrustDevice.initPage()
  }
}
</script>

5.3 在业务节点获取 blackbox

异步回调（推荐）

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

Promise / await（async 函数内）

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

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

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

6. init 配置项说明

支持端：

android / ios / harmony / web / mp-weixin / mp-alipay / mp-toutiao / mp-baidu / mp-jd / mp-xhs
参数类型必填说明
partnerstring是合作方编码，全端顶层字段，请联系运营获取
appKeystring是应用标识，android / ios / harmony 各不同，参考获取 appKey
dataCenterstring是部署区域：cn / sg / us / fra / idna（App 端）
h5fmUrlstring否H5 SDK 脚本地址，联系运营获取（web 端必填）
channelstring否渠道标识
appNamestring否应用名称，同一公司不同应用填不同值
debugboolean否反调试，默认关闭；开发阶段建议开启，发布时关闭（android / ios）
timeLimitnumber否网络请求超时秒数，默认 15（android / ios）
locationboolean否是否采集地理位置信息，默认 true（android / ios）
collectLevelstring否降级 blackbox 裁剪长度，'M' 约 2000 字符，默认 5000 字符（android / ios）
IDFAboolean否是否采集广告标识符，默认 true（ios）
deviceNameboolean否是否采集设备名称，默认 true（ios）
runningTasksboolean否是否获取正在运行的任务，默认 true（android）
sensorboolean否是否采集传感器信息，默认 true（android）
readPhoneboolean否是否采集 READ_PHONE_STATE 权限相关信息，默认 true（android）
installPackageListboolean否是否采集安装包列表，默认 true（android）
wifiMacboolean否是否采集 WIFI MAC 地址，默认 false（android）

7. getBlackBoxAsync 参数说明

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

8. 鸿蒙 Harmony 集成指导

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

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

8.1 添加 SDK dependencies

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

"@trustdecision/mobrisk": "latest"

8.2 新增桥接注册文件

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

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

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

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

8.3 module.json5

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

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

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

{ "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 添加权限说明文案

文件路径：

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

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

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

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

8.5 注意事项

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

Updated about 1 month ago

Did this page help you?

Updated about 1 month ago

Did this page help you?