隐私说明

三方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 ~ Beta1 Release(0.0.31-0.0.68)
7. 应鸿蒙生态市场规范，本SDK从2.1.3版本开始转为Har字节码格式；
8. 2.2.0版本及之前版本SDK升级IDE至5.0.3.800+时兼容方案见FAQ；

接入建议：

• 全局必须要接入的接口：初始化接口
• 获取指纹时必须要使用的接口：获取凭证
• 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.800 为例，将SDK文件放到工程中的 libs 文件夹下（没有libs文件夹可以自行创建，不限制文件夹名称），然后在 工程根目录 的 oh-package.json5 文件中增加如下代码：

  "dependencies": {
    "@yidun/protector": "file:./libs/YiDunProtector-2.3.0.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。业务服务端通过此凭证实时获取当前设备的设备指纹。

接入须知：

• 须在 SDK 初始化且用户同意隐私政策后才能调用该接口，网易易盾隐私说明。
• 接口支持同步或者异步模式。

函数原型：

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'; 下个风控版本会原生兼容新版本命名规范.