集成要求
- 请在用户同意隐私协议后加载和采集 SDK
- 获取到的
blackBox请直接透传服务端,不要在客户端缓存 - 建议在应用启动阶段完成加载和采集,在关键业务节点实时获取
blackBox
合规说明
请注意,在贵司的 App 中集成小盾提供的 SDK 产品时:
- 根据《网络安全法》《电信条例》《电信和互联网用户个人信息保护规定》等相关法律法规要求及监管实践中的标准,在贵司的最终用户首次启动 App 并在贵司开始采集信息之前,贵司应以交互界面或设计(如隐私政策弹窗等)向最终用户完整告知收集、使用、与第三方共享最终用户个人信息的目的、方式和范围,并征得最终用户的明示同意。
- 以文字方式向用户告知
- SDK 名称:小盾设备指纹 SDK
- 开发者名称:浙江小盾未来科技有限公司
- 收集个人信息类型:设备类型、设备型号、系统类型、设备软件版本号、设备标识信息ODID(可选)、GPS位置信息(可选)、WIFI信息(含BSSID、SSID、Mac地址,可选)、IP地址(可选)、WIFI状态(可选)、存储空间状态(可选)、屏幕分辨率(可选)、电池电量状态(可选)、运营商(可选)使用目的:提供业务安全和风控服务 ,为确保贵司使用相关服务的合规性,前述隐私政策应涵盖对小盾 SDK 提供服务并采集、处理、使用相关信息的授权,以上内容供贵司参考,具体表述可由贵司根据贵司隐私协议的整体框架和内容自行确定。
- 隐私政策链接:https://xiaodun.com/other/privacy/id=4
- 如因合规要求需要关闭部分采集能力,可通过参数配置关闭对应采集项;如 SDK 支持模块裁剪,也可在依赖阶段排除对应模块。
SDK 信息
| 项目 | 内容 |
|---|---|
| SDK 名称 | 小盾设备指纹 SDK |
| 开发者名称 | 浙江小盾未来科技有限公司 |
| 使用目的 | 提供业务安全和风控服务 |
| SDK 包名 | @trustdecision/mobrisk |
| 版本号 | 1.3.1 |
| MD5 | 9dbc3da6955e5f11983b42e048f8eab9 |
| 个人信息类处理规则 | https://xiaodun.com/other/privacy/id=4 |
| 使用说明 | 合规使用指导 |
| OpenHarmony 三方库中心仓 | https://ohpm.openharmony.cn/#/cn/detail/@trustdecision%2Fmobrisk |
环境要求
| 项目 | 说明 |
|---|---|
| 兼容版本 | API 12 及以上系统 |
| 支持架构 | arm64-v8a、x86_64 |
🤖 AI Prompt
复制 AI 提示词,粘贴到 Codex、Copilot、Claude Code 等AI 编码工具,即可自动生成代码,完成 TD SDK 集成
✨点击复制 AI 提示词
安装配置
安装 SDK
ohpm install @trustdecision/mobrisk
配置 oh-package.json5
在工程的 oh-package.json5 中设置三方包依赖:
{
"dependencies": {
"@trustdecision/mobrisk": "1.3.1"
}
}权限声明
在工程的 module.json5 的 module 节点中补充以下 requestPermissions 配置:
"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"
}
]权限说明
| 权限 | 是否必需 | 用途 | 触发时机 | 不授权影响 |
|---|---|---|---|---|
ohos.permission.INTERNET | 是 | 与服务端通信并上报设备风险数据 | 加载和采集后请求和上报阶段 | 无法完成联网请求与风险数据上报 |
ohos.permission.GET_NETWORK_INFO | 是 | 获取当前网络连接状态 | 加载和采集和数据上报阶段 | 无法准确判断网络状态,可能影响请求稳定性 |
ohos.permission.GET_WIFI_INFO | 是 | 获取 Wi-Fi 接入状态及相关信息 | 设备环境信息采集阶段 | 无法获取部分网络环境信息,影响风险识别效果 |
ohos.permission.STORE_PERSISTENT_DATA | 是 | 允许应用存储持久化数据 | SDK 运行和本地持久化阶段 | 影响 SDK 本地数据存储能力 |
ohos.permission.APPROXIMATELY_LOCATION | 否 | 获取模糊定位信息 | 位置相关信息采集阶段 | 放弃部分位置信息采集,影响部分风险识别能力 |
加载和采集
注意事项
- 请在用户同意隐私协议后再调用
initWithOptions
方法定义
public static async initWithOptions(context: Context, params: TDRiskOption): Promise<void>示例
在用户同意隐私协议后执行以下代码:
import AbilityStage from '@ohos.app.ability.AbilityStage'
import { TDRisk, TDRiskOption } from '@trustdecision/mobrisk'
export default class MyAbilityStage extends AbilityStage {
async onCreate() {
const options: TDRiskOption = {
partnerCode: '请输入您的合作方编码', // 合作方(partnerCode),请填写partnerCode,不要填partnerKey
appKey: '请输入您的appKey', // 配置AppKey,请联系运营获取
dataCenter: TDRisk.DATA_CENTER_CN, // 数据中心参数,列表可以参考下文全部配置说明
}
await TDRisk.initWithOptions(this.context, options)
}
}获取 blackBox
注意事项
- 请在
initWithOptions调用完成后再调用getBlackBoxAsync/getBlackBox - 不要在 App 内缓存返回的
blackBox,每次获取请直接调用对应方法 - 建议首次先使用异步方式获取
blackBox,在异步回调完成后再按需同步获取
方法定义
/**
* 异步获取 blackbox
* @param priorityCache 是否优先返回缓存,默认 false
* false:等待本次数据上报完成后返回最新 blackbox
* true:发起数据上报后优先返回缓存中的 blackbox,可立即返回
*/
public static async getBlackBoxAsync(priorityCache: boolean = false): Promise<string>
/**
* 同步获取 blackbox,直接返回当前可用的 blackbox
*/
public static getBlackBox(): string示例
异步获取
首次及关键业务节点建议使用异步方式获取:
import { TDRisk } from '@trustdecision/mobrisk'
async function getBlackBox() {
const blackBox = await TDRisk.getBlackBoxAsync();
console.info('TD_TS', `async blackBox: ${blackBox}`);
}同步获取
在首次异步获取完成后,可在业务节点按需同步获取:
import { TDRisk } from '@trustdecision/mobrisk'
function getBlackBox() {
const blackBox = TDRisk.getBlackBox();
console.info('TD_TS', `sync blackBox: ${blackBox}`);
}最佳实践
- 在应用启动阶段、用户同意隐私协议后完成 SDK 加载和采集
- 在注册、登录、支付、营销等关键业务节点实时获取
blackBox - 首次异步获取完成后再依赖同步结果
- 不要复用历史
blackBox
状态检查
- 加载和采集成功时,可在日志中看到
TD_TS: td sdk init success - SDK 上报数据成功时,
getBlackBoxAsync()返回结果通常为 26 固定长度的正常blackBox - 异常情况下,
getBlackBoxAsync()返回结果长度可能明显增加,详情可参考 正常 blackBox 和降级 blackBox 的差异
获取 SDK 版本号
const version: string = TDRisk.getSDKVersion()全部配置
| 配置 key | 说明 | 示例代码 | 移除字段 |
|---|---|---|---|
| partnerCode(必须) | 合作方编码,请联系运营获取 | options["partnerCode"] = "请输入您的合作方编码" | |
| appKey(必须) | 应用标识,提供 App 的包名 bundleName 后联系运营获取 appKey bundleName 获取方式AppScope/app.json5 内 bundleName 对应的 value | options["appKey"] = "请输入您的appKey" | |
| dataCenter(必须) | 数据中心地区: TDRisk.DATA_CENTER_CN (中国) ❗️变更点:country已废弃但目前仍能生效,建议改用dataCenter | options["dataCenter"] = "请输入您所在的数据中心地区" | |
| appName | 应用名称,请联系运营获取 | options["appName"] = "请输入您的appName" | |
| disableGPS | 禁止采集 GPS 位置信息,默认允许 | options["disableGPS"] = true | latitude、longitude、altitude、gpsSwitch |
| disableWifiInfo | 禁止采集 wifi 信息(包含BSSID、SSID),默认允许 | options["disableWifiInfo"] = true | bssid、ssid |
| disableODID | 禁止采集odid,默认允许 | options["disableODID"] = true | odid |
| disableIP | 禁止采集IP地址,默认允许 | options["disableIP"] = true | cellIp、wifiIp、vpnIp |
| disableWifiStatus | 禁止采集WIFI状态,默认允许 | options["disableWifiStatus"] = true | networkType、networkNames |
| disableStorageInfo | 禁止采集存储空间状态,默认允许 | options["disableStorageInfo"] = true | totalStorage、availableStorage |
| disableScreenResolution | 禁止采集屏幕分辨率,默认允许 | options["disableScreenResolution"] = true | screenResolution |
| disableBatteryInfo | 禁止采集电池电量状态,默认允许 | options["disableBatteryInfo"] = true | batteryStatus、batteryLevelRatio、batteryPluggedType、batteryTechnology |
| disableCarrierInfo | 禁止采集运营商信息,默认允许 | options["disableCarrierInfo"] = true | simCountryIso、simCarrier、simState |
| disablePrivacyData | 禁止隐私相关信息,默认允许 | options["disablePrivacyData"] = true | screenResolution、deviceType、brand、marketName、batteryStatus、batteryLevelRatio、batteryPluggedType、batteryTechnology、totalStorage、availableStorage、networkType、networkNames、cellIp、wifiIp、vpnIp、simCountryIso、simCarrier、simState、latitude、longitude、altitude、gpsSwitch、bssid、ssid、odid |
| httpTimeOut | 网络请求回调的超时时间,单位毫秒,默认60000 | options["httpTimeOut"] = 60000 | |
| customMessage | 自定义消息,SDK 支持透传和存储 | options["customMessage"] = "customMessage" |
