集成要求

请在用户同意隐私协议后加载和采集 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.2.8`
MD5	a843484eb65f797bef1c8bd8d186d2b1
个人信息类处理规则	https://xiaodun.com/other/privacy/id=4
使用说明	合规使用指导
OpenHarmony 三方库中心仓	https://ohpm.openharmony.cn/#/cn/detail/@trustdecision%2Fmobrisk

环境要求

项目	说明
兼容版本	`API 12` 及以上系统
支持架构	`arm64-v8a`、`x86_64`

安装配置

安装 SDK

ohpm install @trustdecision/mobrisk

配置 oh-package.json5

在工程的 oh-package.json5 中设置三方包依赖：

{
  "dependencies": {
    "@trustdecision/mobrisk": "1.2.8"
  }
}

权限声明

在工程的 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: 'yourPartnerCode',
      appKey: 'yourAppKey',
      country: 'yourcountry'
    }
    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()

全部配置

参数名	是否必填	说明	默认值	示例代码	移除字段/备注
`partnerCode`	是	合作方编码，请联系运营获取	无	`options.partnerCode = 'partnerCode'`	必填
`appKey`	是	应用标识，提供 App 的包名 `bundleName` 后联系运营获取	无	`options.appKey = 'appKey'`	`bundleName` 可在 `AppScope/app.json5` 中获取
`country`	是	数据中心地区	无	`options.country = TDRisk.COUNTRY_CN`	当前文档仅展示中国区示例
`appName`	否	应用名称，请联系运营获取	空	`options.appName = 'appName'`	可选
`disableWifiInfo`	否	禁止采集 Wi-Fi 信息（包含 BSSID、SSID、MAC 地址）	`false`	`options.disableWifiInfo = true`
`disableODID`	否	禁止采集 ODID	`false`	`options.disableODID = true`
`disableIP`	否	禁止采集 IP 地址	`false`	`options.disableIP = true`
`disableWifiStatus`	否	禁止采集 Wi-Fi 状态	`false`	`options.disableWifiStatus = true`
`disableStorageInfo`	否	禁止采集存储空间状态	`false`	`options.disableStorageInfo = true`
`disableScreenResolution`	否	禁止采集屏幕分辨率	`false`	`options.disableScreenResolution = true`
`disableBatteryInfo`	否	禁止采集电池电量状态	`false`	`options.disableBatteryInfo = true`
`disableCarrierInfo`	否	禁止采集运营商信息	`false`	`options.disableCarrierInfo = true`
`disablePrivacyData`	否	禁止采集隐私相关信息	`false`	`options.disablePrivacyData = true`
`httpTimeOut`	否	网络请求回调超时时间，单位毫秒	`60000`	`options.httpTimeOut = 60000`	可选
`customMessage`	否	自定义消息，SDK 支持透传和存储	空	`options.customMessage = 'customMessage'`	可选