Harmony应用集成SDK

背景信息

App防护SDK主要用于对通过App客户端发起的请求进行签名。WAF服务端通过校验App请求签名，识别App业务中的风险、拦截恶意请求，实现App防护的目的。

关于App防护提供的SDK所涉及的隐私政策，请参见Web应用防火墙App防护SDK隐私政策。

使用限制

• 需要在Harmony Next 4.1及以上版本的系统运行，API版本最低支持12。

• init初始化接口存在耗时操作，调用后不能立即同步调用vmpSign接口，请确保SDK的初始化接口和签名接口调用时间间隔2秒以上。

• 滑块创建cptCreate涉及UI操作，需要在主线程中进行调用。

• 不支持模拟器模式调试。

• 仅支持开启字节码打包方案。

前提条件

• 已获取Harmony应用对应的SDK。

  获取方法：请提交工单，联系产品技术专家获取SDK。

  说明

  Harmony应用对应的SDK包含1个HAR文件，文件名为HarmonyOS-AliTigerTally-X.Y.Z-date.har，其中X.Y.Z表示版本号，date表示打包日期。

• 已获取SDK认证密钥（即appkey）。

  开启BOT管理后，即可在BOT管理 > App防护列表中，单击获取并复制appkey，获取SDK认证密钥。该密钥用于发起SDK初始化请求，需要在集成代码中使用。

  

  说明

  每个阿里云账号拥有唯一的appkey（适用于所有接入WAF防护的域名），且Android、iOS和Harmony应用集成SDK时都使用该appkey。

  认证密钥示例：****OpKLvM6zliu6KopyHIhmneb_****u4ekci2W8i6F9vrgpEezqAzEzj2ANrVUhvAXMwYzgY_****vc51aEQlRovkRoUhRlVsf4IzO9dZp6nN_****Wz8pk2TDLuMo4pVIQvGaxH3vrsnSQiK****。

步骤一：新建工程

以DevEco Studio工具为例，新建一个Harmony工程，并按照配置向导完成创建。创建好的工程目录如下图所示。

步骤二：集成HAR包

1. 将HarmonyOS-AliyunTigerTally-X.Y.Z-date.tgzSDK包解压，将获取到的HAR文件拷贝到工程中存放HAR包的目录。

   建议参考鸿蒙官方文档放置于libs目录下。

2. 打开App的oh-package.json5文件，在dependencies中添aliyuntigertally、captcha编译依赖，示例如下：

   重要

   您需要将aliyuntigertally-X.Y.Z-date.har文件的版本号X.Y.Z替换成您获取的HAR文件的版本号。

   {
     ...
     "dependencies": {
       "aliyuntigertally": "file:../libs/aliyuntigertally-X.Y.Z-date.har",
       "captcha": "file:../libs/aliyuncaptcha-X.Y.Z-date.har",
       ...
     }
   }

步骤三：为应用申请权限

为增强SDK的防护效果，当前需要以下权限：

步骤四：添加集成代码

import { TigerTallyAPI, TTCode } from 'aliyuntigertally';
import { TTCaptcha, TTCaptchaOption, TTCaptchaListener} from 'aliyuntigertally';

最佳实践示例

import http from '@ohos.net.http';
import { BusinessError } from '@ohos.base';

import { TigerTallyAPI, TTCode } from 'aliyuntigertally';
import { TTCaptcha, TTCaptchaOption, TTCaptchaListener} from 'aliyuntigertally';

@Entry
@Component
struct Index {
  
  build() {
    ...
  }
  
  aboutToAppear() {
    this.onTest();
  }

  async onTest() {
    
    const APP_KEY: string = "xxxxxx";
    const APP_URL: string = "xxxxxx";
    const APP_HOST: string = "xxxxxx";
    
    // 初始化
    let options: Map<string, string> = new Map<string, string>();
    options.set("IPv6", "0");// 配置为IPv6
    options.set("Intl", "0");// 配置为中国内地上报
    let retCode: number = TigerTallyAPI.init(getContext(this), APP_KEY, options, null);
    console.log("TigerTally init:", retCode);

    // 不能立即同步调用
    const sleep = (duration: number) => {
      return new Promise<void>(resolve => setTimeout(resolve, duration));
    };
    await sleep(2000);

    // 数据签名
    let data: string = "i am the request body, encrypted or not!";
    let wtoken: string = TigerTallyAPI.vmpSign(0, data);
    console.log("TigerTally vmpSign:", wtoken);

    // 请求接口
    this.doPost(APP_URL, APP_HOST, wtoken, data, (code, cookie, body) => {
      // 判断是否需要显示滑块
      let recheck: number = TigerTallyAPI.cptCheck(cookie, body);
      console.log("TigerTally captcha check:", recheck);

      if (recheck === 0) return;
      this.doShow();
    });
  }

  // 显示滑块
  async doShow() {
    console.log("滑块显示");

    let option: TTCaptchaOption = new TTCaptchaOption();
    // option.cancelable = false;

    let captcha: TTCaptcha = TigerTallyAPI.cptCreate(this.getUIContext(), option, {
      success: (captcha: TTCaptcha, code: string) => {
        console.log("captcha success:", code);
        captcha.dismiss();
      },
      fail: (captcha: TTCaptcha, code: string) => {
        console.log("captcha failed:", code);
        captcha.dismiss();
      }
    });
    captcha.show();
  }

  // 发送请求
  async doPost(url: string, host: string, wtoken: string, body: string,
    callback: (code: number, cookie: string, body: string) => void): Promise<void> {
    let response_code: number = 0;
    let response_body: string = "";
    let response_cookie: string = "";

    try {
      let httpRequest = http.createHttp();
      let response: http.HttpResponse = await new Promise<http.HttpResponse>((resolve, reject) => {
        httpRequest.request(
          url,
          {
            method: http.RequestMethod.POST,
            header: {
              "Content-Type": "text/x-markdown",
              "User-Agent": "",
              "Host": host,
              "wToken": wtoken,
            },
            extraData: body.length > 0 ? body : undefined,
            connectTimeout: 12000,
          },
          (err: BusinessError, data: http.HttpResponse) => {
            if (!err) {
              resolve(data);
            } else {
              reject(err);
            }
            httpRequest.destroy();
          }
        );
      });

      if (response != null) {
        response_code = response.responseCode;
        let success: boolean = (response_code === 200);

        if (success) {
          response_body = response.result ? response.result.toString() : "";
          response_cookie = response.header["set-cookie"] ? response.header["set-cookie"].join(";") : "";
        } else {
          response_body = response.result ? response.result.toString() : "";
        }
      } else {
        response_code = -1;
      }

      console.log("response code:", response_code);
      console.log("response body:", response_body);
      console.log("response cookie:", response_cookie);

    } catch (error) {
      console.log("response error:", error.code, error.message);
      response_code = -1;
      response_body = error.message;
    } finally {
      if (callback != null) {
        callback(response_code, response_cookie, response_body);
      }
    }
  }
}