智能风控 鸿蒙 端接入文档(ArkTS)

2024.10.11 14:18:48

    隐私说明

    三方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;
    

    接入建议:

    接入步骤

    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'; 下个风控版本会原生兼容新版本命名规范.
    
    Online Chat Tel:95163223 Free trial