设备指纹 鸿蒙 端接入文档（ArkTS）
2024.10.14 14:12:24
隐私说明
三方SDK采集说明
为保证符合国家隐私合规政策，需要在隐私政策中的三方SDK列表中补充易盾设备指纹SDK相关说明
易盾设备指纹SDK（鸿蒙版）
第三方公司名称：杭州网易智企科技有限公司
集成方式：内嵌SDK
共享信息：设备唯一识别码：OAID、AAID；设备运行状态（SIM卡状态、USB状态、充电状态、电池容量及电量、启动时间）；设备基本信息（设备品牌及型号、设备厂商、设备所运行系统版本、名称、系统内核信息、CPU型号、设备内存及存储大小、屏幕亮度及分辨率、设备架构、基带信息、辅助功能列表、模拟器类型）；日志信息（网络连接类型及状态、IP地址、运营商信息、网络代理、WIFI信息）、自身安装包信息（包名，版本号，签名）
使用目的：用于风险控制、反欺诈、设备环境风险，以保障账户和交易安全
使用场景：提高应用及合作伙伴服务的安全性，保证用户人身财产安全、预防钓鱼网站、欺诈、网络漏洞、计算机病毒、网络入侵等风险
共享方式：（内部）接口共享
第三方隐私链接：https://dun.163.com/clause/privacy
接入说明
接入 “设备指纹” SDK，开发者需要完成以下步骤：
1. 根据应用/游戏开发平台，将SDK拷贝到指定的工程目录，并修改项目配置；
2. 初始化SDK（初始化接口：init）；
3. 调用getToken获取token信息（getToken接口：getToken）；
4. 验证SDK接入是否正确；
5. 可选择性的接入相关功能性接口；
6. 本SDK支持系统版本：Beta2 Developer ~ 12 Release(0.0.31-0.0.71)
7. 应鸿蒙生态市场规范，本SDK从2.1.3版本开始转为Har字节码格式；
8. 2.2.0版本及之前版本SDK升级IDE至5.0.3.800+时兼容方案见FAQ；
9. 应华为要求，11.10之后仅允许API 12 Release的SDK上架，2.3.1版本完成适配
接入建议：
- 全局必须要接入的接口：初始化接口
- 获取指纹时必须要使用的接口：获取凭证
- Worker方式接入参考：Worker方式接入
接入步骤
SDK 涉及到以下文件：
YiDunProtector-HarmonyNEXT-x.x.x.zip //其中x.x.x是对应版本号
注意：
- 自2.1.3版本开始，SDK原HSP格式废弃，转为Har字节码包格式，接入方式与HSP相同，仅更改SDK名称即可
- SDK只支持64位架构，默认包含arm64-v8a和x86_64两个架构
HSP迁移至Har
若之前未接入过设备指纹HSP版本的SDK，可以直接跳过迁移步骤
迁移步骤：
- 将新的指纹Har包拷贝到原HSP对应目录或新建目录，将工程根目录 的 oh-package.json5 文件文件中的sdk名称替换一下即可，如之前是file:./libs/YiDunProtector-x.x.x.tgz，只需要替换成file:./libs/YiDunProtector-2.1.3.har后点击Sync Now刷新工程即可
升级2.3.0+ SDK
由于Deveco Studio 5.0.3.800要求工程级build-profile.json5文件的useNormalizedOHMUrl字段为true时，oh-package.json5中依赖的包使用的别名和依赖包的oh-package.json5的name必须一致，因此后续版本的name会统一更改为@yidun/protector，原接入历史版本SDK需进行修改，当接入版本为2.3.0之前的版本时，兼容该版本IDE请见文档的FAQ
import { NEDevice, NEResult, NEDeviceConfig } from '@ohos/YiDunProtector';
更改为
import { NEDevice, NEResult, NEDeviceConfig } from '@yidun/protector';
导入SDK
（1）以 DevEco Studio 5.0.3.900 为例，将SDK文件放到工程中的 libs 文件夹下（没有libs文件夹可以自行创建，不限制文件夹名称），然后在 工程根目录 的 oh-package.json5 文件中增加如下代码：
"dependencies": {
"@yidun/protector": "file:./libs/YiDunProtector-2.3.1.har", //其中x.x.x为版本，新的字节码Har包接入方式
},
（2）点击右上方的Sync Now刷新工程
（3）在工程根目录build-profile.json5中添加useNormalizedOHMUrl属性，具体可参考华为官网引用HAR参考
"products": [
{
"name": "default",
"signingConfig": "default",
"compatibleSdkVersion": "5.0.0(12)",
"runtimeOS": "HarmonyOS",
//添加如下内容
"buildOption": {
"strictMode": {
"useNormalizedOHMUrl": true
},
}
}
]
（4）如果没有弹出Sync Now选项，可手动点击File -> Sync and Refresh Project
SDK 接入调用说明
SDK 初始化接口（init）
接口用途：
用于初始化设备指纹 SDK。
接入须知：
- 使用其他接口之前，必须先调用初始化接口（init），建议在应用/游戏启动过后第一时间调用（初始化后，并不会获取任何个人隐私相关信息）；
- 该接口为 必须调用接口。
函数原型：
import { NEDevice, NEResult, NEDeviceConfig } from '@yidun/protector';
static init(context: Context, config?: NEDeviceConfig): number;
参数说明：
| 参数 | 说明 | 必要性 |
|---|---|---|
| context | 当前环境的上下文 | 必填 |
| config | 配置类的对象 | 可选，不需要可忽略 |
返回值说明：
| code | 说明 |
|---|---|
| 200 | 初始化成功 |
| 1007 | context为空或参数错误 |
| 1011 | 加载so失败 |
| 1012 | 校验私有化host失败，格式不正确 |
配置类NEDeviceConfig设置：
(1) 设置渠道信息
channel: string = '';
若需要传递当前应用包体来源渠道可调用该接口（比如：应用宝渠道编号/信息）。
(2) 设置禁止采集项
privacyList: Array<string> = [] //如['wifi']表示不采集wifi名称和wifimac信息
若需要禁止某些数据采集可调用该接口，目前仅支持配置wifi相关，不调用默认会采集
(3) 设置自定义域名
host?: string = '';//自定义域名，私有化时需要使用，格式为https://xxx.xxx.xxx，非完整url地址，仅host
若需要私有化部署，需设置该域名为私有化域名，saas服务时，请勿配置该参数
如需要示例 demo 请联系易盾获取。
示例代码：
....
import { NEDevice, NEResult, NEDeviceConfig } from '@yidun/protector';
....
@Entry
@Component
struct Index {
@State message: string = 'Hello World';
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
.onClick(() => {
let ret = NEDevice.init(getContext(this), {
host: 'https://fp-upload-test.dun.163.com' // 此处演示使用自定义域名
});
hilog.info(0x0000, 'testTag', '%{public}s %{public}d', 'init dfp status', ret);
});
}
.width('100%')
}
.height('100%')
}
}
获取凭证（getToken）
接口用途：
用于获取设备指纹唯一凭证 token。业务服务端通过此凭证实时获取当前设备的设备指纹。
接入须知：
函数原型：
static async getToken(appId: string, timeout: number): Promise<NEResult>;
参数说明：
| 参数 | 说明 | 必要性 |
|---|---|---|
| appId | 业务 ID | 必填，由易盾后台分配（32位） |
| timeout | 函数超时时间 | 必填，单位毫秒，[400,10000]，此区间外的默认为3000，表示getToken函数超时时间，超过时间自动降级为离线token |
返回值说明：
NEResult类说明：
interface NEResult {
code: number;
token: string;
}
变量说明：
| 变量 | 说明 |
|---|---|
| code | 结果码，不同结果码含义如下：200：表示获取token成功，201：表示获取离线token成功，其他结果码均表示调用失败；1000：采集信息失败；1002：解析返回值失败；1003：SDK未初始化；1005：校验返回值失败；1007：appId不合法；4xx，5xx均为服务端错误码 |
| token | 当 code 为200时，返回正常token（32位）。当网络状态不佳或者超时时，会返回离线 token（几KB左右），code为201 |
示例代码：
....
import { NEDevice, NEResult, NEDeviceConfig } from '@yidun/protector';
....
//异步模式，通过promise进行异步调用
NEDevice.getToken("appid", 5000).then((result) => {
hilog.info(0x0000, 'testTag', 'getAsync dfp token code:%{public}d token:%{public}s', result.code, result.token);
});
//同步模式，通过await将结果直接返回到result中
let result = await NEDevice.getToken("appid", 5000);
hilog.info(0x0000, 'testTag', 'getSync dfp token code:%{public}d token:%{public}s', result.code, result.token);
Worker方式接入
方法用途：
用于适配部分框架无法直接支持ArkTS接入的问题，如团结引擎，需使用Worker进行接入，需注意目前仅支持单Worker调用。
接入须知：
- 需保证初始化时能够正确的传递context变量，保证指纹init接口可以初始化成功
示例代码：
如团结引擎可在TuanjiePlayerAbility.ts类的onCreate方法中，使用自带Worker类或自定义Worker来实现指纹SDK初始化，以下为自定义Worker初始化示例。
workerInstance: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/MyWorker.ets');
//传递context信息，必须在UI线程调用，如需要传递额外的信息可通过其他变量传递，团结引擎可使用this.context
this.workerInstance.postMessage({ type: 'initDfp', data: getContext(this) });
//在UI线程监听worker线程的传递信息，并根据返回值进行处理
this.workerInstance.onmessage = (e: MessageEvents) => {
let data: ESObject = e.data;
switch (data.type) {
case "dfpCode":
hilog.info(0x0000, 'testTag', '%{public}s %{public}d', 'init dfp status', data.data);
if (data.data == 200) {
//当初始化成功时，执行获取token的方法，通过type传递给worker线程，此处为演示方法，应根据自身业务需要在必要的地方进行调用，避免产生隐私合规问题
this.workerInstance.postMessage({ type: 'getDfpToken' });
}
break;
case "dfpToken":
//监听worker线程调用指纹getToken方法的返回值
hilog.info(0x0000, 'testTag', 'get dfp token %{public}s',JSON.stringify(e.data));
break;
}
}
Worker线程内处理方式
workerPort.onmessage = (e: MessageEvents) => {
let data: ESObject = e.data;
switch (data.type) {
case "initDfp":
let config: NEDeviceConfig = new NEDeviceConfig();
config.channel = "testChannel";
config.privacyList = ['wifi'];
//此处data.data为UI线程传递过来的context变量
let ret: number = NEDevice.init(data.data, config);
hilog.info(0x0000, 'testTag', '%{public}s %{public}d', 'init dfp status', ret);
workerPort.postMessage({ type: 'dfpCode', data: ret })
break;
case "getDfpToken":
NEDevice.getToken("appid", 5000).then((result) => {
hilog.info(0x0000, 'testTag', 'get dfp token code:%{public}d token:%{public}s',
result.code, result.token);
workerPort.postMessage({ type: 'dfpToken', data: result })
});
break;
}
}
常见问题FAQ
1. 当前SDK是否支持beta1开发者版本.
答：功能上实际支持到3.0.0.25系统，但由于华为约束的编译方式，导致beta1版本IDE无法引用，需要至少5.0.3.500的版本才可以编译成功.
2. linux或者开启caseSensitiveCheck时提示Cannot resolved import statement @ohos/YiDunProtector/index. Please check the case.
答：目前临时方案可以强制引入from '@ohos/YiDunProtector/Index';
3. sdk接入后运行在模拟器上出现崩溃.
答：由于模拟器不强制要求签名，sdk在获取签名时出现空指针，临时可以通过签名hap避免该问题，从2.2.0 sdk版本后会兼容该问题.
4. IDE升级到5.0.3.800后，如果工程级build-profile.json5文件的useNormalizedOHMUrl字段为true，当oh-package.json5中依赖的包使用的别名和依赖包的oh-package.json5的name不一致时报错.
答：1.参考https://developer.huawei.com/consumer/cn/doc/harmonyos-releases-V5/ide-changelogs-nb1-V5适配指导或者更改引入方式为import { AntiCheatResult, HTProtect} from 'yidunprotector'; 下个风控版本会原生兼容新版本命名规范.
