> >

资源与概述

GeeGaurd HarmonyOS SDK 提供给集成鸿蒙 Next 原生客户端开发的开发者使用。

环境要求

条目	资源
开发目标	HarmonyOS Next
开发环境	DevEco Studio 5.0.3.800
API 版本	API 12
SDK 三方依赖	无

集成

获取 SDK

请联系您的对接人。

导入 SDK

将 zip 包中的 .har 文件（包括 geetest_geeguard_harmonyos_vx.y.z_date.har ）拖拽到工程中的 libs 文件夹下，在拖入 .har 到 libs 文件夹后，还要检查 .har 是否被添加到 Library，要在项目的 oh-package.json5 下添加如下代码：

"dependencies": {
    "geeguardSdk": "file:./libs/geetest_geeguard_harmonyos_vx.y.z_date.har"
}

添加权限声明

// 必须权限
ohos.permission.INTERNET
ohos.permission.STORE_PERSISTENT_DATA
ohos.permission.GET_NETWORK_INFO
// 可选权限
ohos.permission.APP_TRACKING_CONSENT

权限说明

权限名称	功能说明	使用场景	备注
INTERNET	允许应用程序联网	用于访问服务	必须
GET_NETWORK_INFO	访问当前网络状态	判断当前网络处于移动网络或 WiFi 网络需要此权限	必须
STORE_PERSISTENT_DATA	持久化存储数据	用于安全风控和生成新的设备标识	必须
APP_TRACKING_CONSENT	获取开放匿名设备标识符（OAID）	用于安全风控和生成新的设备标识	动态权限, 可选

配置混淆规则

极验 SDK 已做混淆处理，集成时请带上混淆规则，勿再次混淆 SDK

调用逻辑

在后台注册 AppID
使用 AppID 获取 GeeGuardReceipt

集成代码参考下方的代码示例

代码示例

该示例适用于 1.0.0+ 版本

应用启动后立即注册 appID

export default class MainAbilityStage extends AbilityStage {
  // 您申请的 AppID
  private static readonly GEEGUARD_APP_ID = '123456789012345678901234567890ab'

  onCreate() {
    GeeGuard.register(this.context, MainAbilityStage.GEEGUARD_APP_ID);
  }
}

获取 GeeToken

使用 GeeGuard SDK 对数据进行签名，并获取环境检测 GeeToken：

// 直接获取 GeeToken，需在服务端解析结果
async function getGeeToken(context: Context) {
  // 唯一标记本次业务的流水号或凭证，用于防止 GeeToken 从业务场景剥离
  // 如果无防止 GeeToken 从业务场景剥离的需求，data 可以传入 null
  let data = '唯一标记本次业务的流水号或凭证，用于防止 GeeToken 从业务场景剥离';

  let receipt = await GeeGuard.fetchReceipt(context, data);
  if (!receipt || !receipt.geeToken) {
    console.error('无法获取 GeeGuardReceipt，请检查是否已通过 GeeGuard.register(appId) 注册 AppID');
    return;
  }

  // 随业务数据一同提交，请在服务端获取最终的环境识别结果及指纹
  // 接口参数请参考服务端文档
  console.log(`GeeToken: ${receipt.geeToken}`);
}

// 获取 respondedGeeToken，需在服务端解析结果
// 此方法回调为异步
function getRespondedGeeToken(context: Context) {
  // 唯一标记本次业务的流水号或凭证，用于防止 GeeToken 从业务场景剥离
  // 如果无防止 GeeToken 从业务场景剥离的需求，data 可以传入 null
  let data = '唯一标记本次业务的流水号或凭证，用于防止 GeeToken 从业务场景剥离';

  GeeGuard.submitReceipt(context, data, {
    onCompletion: (status: number, receipt: GeeGuardReceipt | undefined) => {
      if (status === 200) {
        if (!receipt || !receipt.respondedGeeToken) {
          console.error('无法获取 respondedGeeToken，请检查是否已通过 GeeGuard.register(appId) 注册 AppID');
          return;
        }
        // 随业务数据一同提交，请在服务端获取最终的环境识别结果及指纹
        // 接口参数请参考服务端文档
        console.log(`RespondedGeeToken: ${receipt.respondedGeeToken}`);
      } else {
        // SDK 获取 respondedGeeToken 错误, 请参考下面的错误码清单
        console.log(`Status: ${status}`);
      }
    }
  });
}

错误码清单

异步获取方法 GeeGuard.submitReceipt(Context, string, GeeGuardCallbackHandler) 中可能返回的错误码有：

错误码	描述
-200	未注册 AppID，请在启动后注册 AppID
-300	网络错误，详细见日志中 tag 为 `GeeGuard` 的 stacktrace
-500	服务响应格式异常，详细请查看 `receipt.originalResponse`
-501	服务响应失败，详细请查看 `receipt.originalResponse`

查询 GeeToken 结果

将 respondedGeeToken 或 GeeToken 跟随业务数据一起提交到业务的服务端，服务端再向极验设备指纹服务查询结果。详细见服务端文档。

更新说明

版本号	更新内容	日期
1.0.1	1. 支持 x86_64 架构 2. 修复部分已知的问题	2024-09-11
1.0.0	1. 初始版本	2024-06-18