API Reference
English

HarmonyOS

集成要求

合规说明

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

1.1 根据《网络安全法》《电信条例》《电信和互联网用户个人信息保护规定》等相关法律法规要求及监管实践中的标准,在贵司的最终用户首次启动App并在贵司开始采集信息之前,贵司应以交互界面或设计(如隐私政策弹窗等)向最终用户完整告知收集、使用、与第三方共享最终用户个人信息的目的、方式和范围,并征得最终用户的明示同意。

1.2 为向贵司提供业务安全和风控服务,同盾SDK将采集、处理、使用用户的手机终端唯一标志信息IDFA、Android ID、OAID、GAID、MAC 地址、无线IP地址、WIFI列表、无线路由器标识(BSSID、SSID)、设备类型、设备型号、系统类型、位置信息(粗略位置信息、精准位置信息)、登录 IP 地址等设备信息。为确保贵司使用相关服务的合规性,前述隐私政策应涵盖对同盾SDK提供服务并采集、处理、使用相关信息的授权,以下条款内容供贵司参考,具体表述可由贵司根据贵司隐私协议的整体框架和内容自行确定:

同盾SDK:为了业务安全和风控,我司使用了同盾 SDK,该 SDK 需要获取您的手机终端设备标识 IDFA、Android ID、OAID、GAID、MAC 地址、无线IP地址、WIFI列表、无线路由器标识(BSSID、SSID)、设备类型、设备型号、系统类型、位置信息(粗略位置信息、精准位置信息)、登录 IP 地址、应用程序列表、运行中进程信息、网络制式、设备软件版本号、传感器(光传感器、重力传感器、磁场传感器、加速度传感器、陀螺仪传感器、心率传感器)相关设备信息,用于设备欺诈风险识别。

同盾隐私协议:<https://www.tongdun.cn/other/privacy/id=1>

环境要求

说明
兼容版本API12及以上系统
支持架构arm64-v8a, x86_64

集成步骤

安装配置

安装说明

ohpm install @trustdecision/mobrisk

集成 SDK

在工程的 oh-package.json5 中设置三方包依赖,配置示例如下:

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

权限声明

在工程的 module.json5 中声明以下权限:

 <!--必选权限--> 
 ohos.permission.INTERNET
 ohos.permission.GET_NETWORK_INFO
 ohos.permission.GET_WIFI_INFO
 ohos.permission.STORE_PERSISTENT_DATA

权限说明

权限说明
ohos.permission.INTERNET(必选)允许程序访问网络连接,发送请求与服务器进行通信
ohos.permission.GET_NETWORK_INFO(必选)获取网络连接状态信息
ohos.permission.GET_WIFI_INFO(必选)获取当前 WiFi 接入的状态以及 WLAN 热点的信息
ohos.permission.STORE_PERSISTENT_DATA(必选)允许应用存储持久化的数据

初始化

方法定义

  /**
   * 设备指纹初始化
   * @param context 上下文
   * @param params 初始化参数
   */
  public static async initWithOptions(context: Context, params: TDRiskOption): Promise<void> 

获取设备信息

注意事项

  • 请在 initWithOptions 后调用 getDeviceInfo

方法定义

/**
 * 异步方式获取deviceinfo
 */
public static async getDeviceInfo(): Promise<TDDeviceInfo>

最佳实践

  1. 在应用首次加载时的 onCreate 方法中调用初始化并异步获取 blackBox
import AbilityStage from '@ohos.app.ability.AbilityStage';
import { TDDeviceManager, TDRiskOption } from '@trustdecision/mobrisk';

export default class MyAbilityStage extends AbilityStage {
 async onCreate() {
    // 应用的HAP在首次加载的时,为该Module初始化操作
    const options: TDRiskOption = {
      /*************************** 必传 ***************************/
      partnerCode: 'demo', // 同盾的合作⽅编码,请填写⾃身的合作⽅编码
      appKey: 'appKey', // 配置AppKey,请联系同盾运营获取
      country: TDRisk.COUNTRY_CN, // 国家地区参数,列表可以参考下文全部配置说明
      /*************************** 必传 ***************************/
    }
    if (⽤户同意隐私协议) {
      await TDDeviceManager.initWithOptions(this.context, options)
    }
  }
}
  1. 在实际业务节点获取设备信息
// 比如注册的时候
async function register(): Promise<void> {
  // ...
   TDDeviceManager.getDeviceInfo()
    .then((deviceInfo: TDDeviceInfo) => {
      // TDDeviceInfo
        // fpVersion: SDK版本号
        // blackBox: 本次采集的blackBox
        // anonymousId: 当前设备的匿名ID
        // deviceRiskScore: 设备风险分数
        // apiStatus: API状态信息
        // sealedResult: 密封结果
      Logger.debug('TD_TS',`init & getDeviceInfo success ${JSON.stringify(deviceInfo, null,2)}`)
    });
  //...
}

状态检查

  1. 加载成功会在 logcat中打印以下日志:
TD_TS: td sdk init success
  1. 当getDeviceInfo() 回调的 code == 0 时即代表获取设备信息成功

响应结果

getDeviceInfo() 函数会在 onResult 方法中返回响应数据,包含以下信息。sealedResult 仅在启用了客户端密封结果时返回该信息。

字段描述
anonymousId设备匿名ID,设备标识
blackBox调用日志查询标识
fpVersionSDK版本号
deviceRiskScore当前设备风险分
sealedResult加密的设备信息,二进制 Base64 编码字符串,仅在客户端密封结果开启时返回

其他说明

获取版本号

TDDeviceManager.getSDKVersion()

全部配置

配置 key说明示例代码
partnerCode(必须)合作方编码,请联系运营获取options["partnerCode"] = "请输入您的合作方编码"
appKey(必须)应用标识,提供 App 的包名 bundleName 后联系运营获取 appKey
bundleName 获取方式:AppScope/app.json5 内 bundleName 对应的 value
options["appKey"] = "请输入您的appKey"
country(必须)数据中心地区: TDRisk.COUNTRY_CN (中国)options["country"] = "请输入您所在的国家地区"
appName应用名称,请联系运营获取options["appName"] = "请输入您的appName"
disableGPS禁止采集 GPS 位置信息,默认允许options["disableGPS"] = true
disableWifiInfo禁止采集 wifi 信息,默认允许options["disableWifiInfo"] = true
disableODID禁止采集odid,默认允许options["disableODID"] = true
httpTimeOut网络请求回调的超时时间,单位毫秒,默认60000options["httpTimeOut"] = 60000
customMessage自定义消息,SDK 支持透传和存储options["customMessage"] = "customMessage"

状态码说明

调用TDDeviceManager.getDeviceInfo()方法,回调中TDDeviceAPIStatus类型的参数保存着SDK的状态信息,它的定义如下:

export class TDDeviceAPIStatus {
  code: number;
  
  message: string;
  
  getCode(): number {
    return this.code;
  }
  
  getMessage(): string {
    return this.message;
  }
}

code和message对应值如下表:

code

message

备注

0

Success.

成功

1000

Invalid parameters.

传入的参数无效

1001

SDK error.

SDK 发生异常,可能原因:
1、未调用初始化函数
2、so文件加载失败

1002

Network error.

网络错误

1003

API error.

后端接口返回错误

1004

Traffic limit.

网关限流

1100

Unknown error

未知错误