HarmonyOS

集成要求

  • 请在用户同意隐私协议后加载和采集 SDK
  • 获取到的 blackBox 请直接透传服务端,不要在客户端缓存
  • 建议在应用启动阶段完成加载和采集,在关键业务节点实时获取 blackBox

合规说明

请注意,在贵司的 App 中集成小盾提供的 SDK 产品时:

  1. 根据《网络安全法》《电信条例》《电信和互联网用户个人信息保护规定》等相关法律法规要求及监管实践中的标准,在贵司的最终用户首次启动 App 并在贵司开始采集信息之前,贵司应以交互界面或设计(如隐私政策弹窗等)向最终用户完整告知收集、使用、与第三方共享最终用户个人信息的目的、方式和范围,并征得最终用户的明示同意。
  2. 以文字方式向用户告知
    • SDK 名称:小盾设备指纹 SDK
    • 开发者名称:浙江小盾未来科技有限公司
    • 收集个人信息类型:设备类型、设备型号、系统类型、设备软件版本号、设备标识信息ODID(可选)、GPS位置信息(可选)、WIFI信息(含BSSID、SSID、Mac地址,可选)、IP地址(可选)、WIFI状态(可选)、存储空间状态(可选)、屏幕分辨率(可选)、电池电量状态(可选)、运营商(可选)使用目的:提供业务安全和风控服务 ,为确保贵司使用相关服务的合规性,前述隐私政策应涵盖对小盾 SDK 提供服务并采集、处理、使用相关信息的授权,以上内容供贵司参考,具体表述可由贵司根据贵司隐私协议的整体框架和内容自行确定。
    • 隐私政策链接:https://xiaodun.com/other/privacy/id=4
  3. 如因合规要求需要关闭部分采集能力,可通过参数配置关闭对应采集项;如 SDK 支持模块裁剪,也可在依赖阶段排除对应模块。

SDK 信息

项目内容
SDK 名称小盾设备指纹 SDK
开发者名称浙江小盾未来科技有限公司
使用目的提供业务安全和风控服务
SDK 包名@trustdecision/mobrisk
版本号1.3.1
MD59dbc3da6955e5f11983b42e048f8eab9
个人信息类处理规则https://xiaodun.com/other/privacy/id=4
使用说明合规使用指导
OpenHarmony 三方库中心仓https://ohpm.openharmony.cn/#/cn/detail/@trustdecision%2Fmobrisk

环境要求

项目说明
兼容版本API 12 及以上系统
支持架构arm64-v8ax86_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.json5module 节点中补充以下 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 对应的 valueoptions["appKey"] = "请输入您的appKey"
dataCenter(必须)数据中心地区: TDRisk.DATA_CENTER_CN (中国) ❗️变更点:country已废弃但目前仍能生效,建议改用dataCenteroptions["dataCenter"] = "请输入您所在的数据中心地区"
appName应用名称,请联系运营获取options["appName"] = "请输入您的appName"
disableGPS禁止采集 GPS 位置信息,默认允许options["disableGPS"] = truelatitude、longitude、altitude、gpsSwitch
disableWifiInfo禁止采集 wifi 信息(包含BSSID、SSID),默认允许options["disableWifiInfo"] = truebssid、ssid
disableODID禁止采集odid,默认允许options["disableODID"] = trueodid
disableIP禁止采集IP地址,默认允许options["disableIP"] = truecellIp、wifiIp、vpnIp
disableWifiStatus禁止采集WIFI状态,默认允许options["disableWifiStatus"] = truenetworkType、networkNames
disableStorageInfo禁止采集存储空间状态,默认允许options["disableStorageInfo"] = truetotalStorage、availableStorage
disableScreenResolution禁止采集屏幕分辨率,默认允许options["disableScreenResolution"] = truescreenResolution
disableBatteryInfo禁止采集电池电量状态,默认允许options["disableBatteryInfo"] = truebatteryStatus、batteryLevelRatio、batteryPluggedType、batteryTechnology
disableCarrierInfo禁止采集运营商信息,默认允许options["disableCarrierInfo"] = truesimCountryIso、simCarrier、simState
disablePrivacyData禁止隐私相关信息,默认允许options["disablePrivacyData"] = truescreenResolution、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网络请求回调的超时时间,单位毫秒,默认60000options["httpTimeOut"] = 60000
customMessage自定义消息,SDK 支持透传和存储options["customMessage"] = "customMessage"