智能风控 鸿蒙 端接入文档(ArkTS)
隐私说明
三方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 { HTProtect, HTProtectConfig, AntiCheatResult } from '@ohos/YiDunProtector';
更改为
import { HTProtect, HTProtectConfig, AntiCheatResult } 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 { HTProtect, HTProtectConfig, AntiCheatResult } from '@yidun/protector';
static init(context: Context, productId: string, config?: HTProtectConfig): number;
参数说明:
参数 | 说明 | 必要性 |
---|---|---|
context | 当前环境的上下文 | 必填 |
productId | 易盾HTP分配的productId,可登录易盾后台获取 | 必填 |
config | 配置类的对象 | 可选,不需要可忽略 |
返回值说明:
code | 说明 |
---|---|
200 | 初始化成功 |
1001 | context为空 |
1002 | 加载so失败 |
1003 | productId格式错误 |
1004 | 校验私有化host失败,格式不正确 |
配置类HTProtectConfig设置:
(1) 设置渠道信息
channel: string = '';
若需要传递当前应用包体来源渠道可调用该接口(比如:应用宝渠道编号/信息)。
(2) 设置禁止采集项
privacyList: Array<string> = [] //如['wifi']表示不采集wifi名称和wifimac信息
若需要禁止某些数据采集可调用该接口,目前仅支持配置wifi相关,不调用默认会采集
(3) 设置自定义域名
host?: string = '';//自定义域名,私有化时需要使用,格式为https://xxx.xxx.xxx,非完整url地址,仅host
若需要私有化部署,需设置该域名为私有化域名,saas服务时,请勿配置该参数
如需要示例 demo 请联系易盾获取。
示例代码:
....
import { HTProtect, HTProtectConfig, AntiCheatResult } 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 config: HTProtectConfig = new HTProtectConfig();
config.channel = "测试";//设置渠道信息
config.privacyList = ['wifi']; //不采集wifi信息
config.host = 'https://dun.163.com'; //仅针对私有化部署时需要设置该属性
let ret = HTProtect.init(getContext(this), "product id", config); //调用初始化,带配置
...
let ret = HTProtect.init(getContext(this), "product id");//调用初始化,不带配置
...
hilog.info(0x0000, 'testTag', '%{public}s %{public}d', 'init htp status', ret);
});
}
.width('100%')
}
.height('100%')
}
}
获取凭证(getToken)
接口用途:
用于关键业务节点风险防控场景中,比如注册、登录、领劵、抽卡、兑换、点赞、评论等业务场景。业务方可通过此接口,获取检测唯一凭证 token。业务服务端通过此凭证实时获取当前用户/玩家风险检测结果,并根据结果进行处置。
接口适用场景为:
1、游戏类应用,当 SDK 数据上报接口被屏蔽导致数据上报失败时,通过 getToken 接口获取 SDK 采集信息,并由客户服务端传递给易盾服务器;
2、全类型应用,在关键业务节点主动调用检测时,通过 getToken 接口获取检测凭证,由客户服务端通过 token 凭证从易盾服务器查询检测结果。
接入须知:
函数原型:
static async getToken(timeout: number, businessId: string): Promise<AntiCheatResult>
参数说明:
参数 | 说明 | 必要性 |
---|---|---|
timeout | 函数超时时间 | 必填,单位毫秒,[400,10000],此区间外默认为3000,建议设置3000,表示getToken函数超时时间,超过时间自动降级为离线token |
businessId | 业务 ID | 必填,由易盾后台分配(32位),并在官网“服务管理”中查询 |
返回值说明:
AntiCheatResult类说明:
interface AntiCheatResult {
code: number;
codeStr: string;
token: string;
}
变量说明:
变量 | 说明 |
---|---|
code | 结果码,不同结果码含义如下:200:表示调用成功,其他结果码均表示调用失败;199:产品ID不合法;201:SDK未初始化;202:在主线程运行;203:businessId不合法;204:其他情况,比如受到攻击 |
codeStr | 结果码对应的字符说明,200:success,199:productId invalid;201:error not init;202:error. run on main thread;203:businessId invalid;204:gen token error |
token | 当 code 为200时,返回正常token(40位)。当网络状态不佳或者超时时,会返回离线 token(几KB左右) |
示例代码:
....
import { HTProtect, HTProtectConfig, AntiCheatResult } from '@yidun/protector';
....
//异步模式,通过promise进行异步调用
HTProtect.getToken(5000, "business id").then((result) => {
hilog.info(0x0000, 'testTag', 'getAsync htp token code:%{public}d token:%{public}s codeStr:%{public}s', result.code, result.token, result.codeStr);
});
//同步模式,通过await将结果直接返回到result中
let result = await HTProtect.getToken(5000, "business id");
hilog.info(0x0000, 'testTag', 'getSync htp token code:%{public}d token:%{public}s codeStr:%{public}s', result.code, result.token, result.codeStr);
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: 'initDun', data: getContext(this) });
//在UI线程监听worker线程的传递信息,并根据返回值进行处理
this.workerInstance.onmessage = (e: MessageEvents) => {
let data: ESObject = e.data;
switch (data.type) {
case "dunCode":
hilog.info(0x0000, 'testTag', '%{public}s %{public}d', 'init htp status', data.data);
if (data.data == 200) {
//当初始化成功时,执行获取token的方法,通过type传递给worker线程,此处为演示方法,应根据自身业务需要在必要的地方进行调用,避免产生隐私合规问题
this.workerInstance.postMessage({ type: 'getDunToken' });
}
break;
case "dunToken":
//监听worker线程调用风控getToken方法的返回值
hilog.info(0x0000, 'testTag', 'get htp token %{public}s',JSON.stringify(e.data));
break;
}
}
Worker线程内处理方式
workerPort.onmessage = (e: MessageEvents) => {
let data: ESObject = e.data;
switch (data.type) {
case "initDun":
let config: HTProtectConfig = new HTProtectConfig();
config.channel = "testChannel";
config.privacyList = ['wifi'];
//此处data.data为UI线程传递过来的context变量
let ret: number = HTProtect.init(data.data, "productCode", config);
hilog.info(0x0000, 'testTag', '%{public}s %{public}d', 'init htp status', ret);
workerPort.postMessage({ type: 'dunCode', data: ret })
break;
case "getDunToken":
HTProtect.getToken(3000, "businessID").then((result: AntiCheatResult) => {
hilog.info(0x0000, 'testTag', 'get htp token code:%{public}d token:%{public}s codeStr:%{public}s',
result.code, result.token, result.codeStr);
workerPort.postMessage({ type: 'dunToken', 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'; 下个风控版本会原生兼容新版本命名规范.