图形认证鸿蒙客户端SDK集成流程-阿里云帮助中心

本文为您介绍图形认证鸿蒙客户端SDK的集成方法及接口的功能示例，该SDK提供给HarmonyOS Next原⽣客户端开发的开发者使⽤。

准备工作

环境要求

条目	资源
开发目标	`HarmonyOS Next`
开发环境	`DevEco Studio 5.0.9.300`及以上
编译版本	`API Version 18 Release`
SDK三方依赖	无

下载SDK

登录号码认证产品控制台，在概览页面右侧API&SDK区域，单击立即下载，进入API&SDK页面，根据页面提示下载并解压对应SDK。

导入SDK

在DevEco Studio中建立或打开您的项目。
将下载的SDK压缩包解压后的.har文件拷贝至您项目的libs扩展库目录下。
在项目的oh-package.json5内添加SDK依赖：

"dependencies": {
    "@alicom/captcha": "file:./libs/alicom_captcha_harmonyos_vx.y.z_date.har"
}

添加权限配置

编辑module.json5文件配置SDK相应权限：

"requestPermissions": [
{
  "name": "ohos.permission.INTERNET",
  "usedScene": {
    "abilities": [
          ...
        ],
        ...
      }
    }
],

混淆规则

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

创建认证方案

使用SDK时，会用到密钥参数信息，请先在图形认证方案管理控制台，新增图形认证方案，获取密钥参数（包括appId、appKey）信息。

配置接口

配置初始化
启动验证
获取验证回调
销毁资源

初始化

SDK初始化配置信息，可在onCreate或onCreateView方法进行初始化。

public static getClient(context: UIContext): AlicomCaptcha4Client;
public init(captchaId: string, config?: AlicomCaptcha4Config): AlicomCaptcha4Client;

参数	类型	说明
context	UIContext	UI实例对象，必须为`page`实例。
captchaId	string	验证ID，请传入在控制台图形认证方案管理页创建认证方案后生成的`appId`。必填参数。
config	AlicomCaptcha4Config	参数配置对象，非必填参数。

启动验证

开始验证流程。

public void verifyWithCaptcha();

取消验证

取消验证流程，关闭验证窗口。

public void cancel();

开启/关闭日志监控

设置开启或关闭日志打印监控。

public void setLogEnable(enable: boolean);

获取验证回调

public AlicomCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public AlicomCaptcha4Client addOnFailureListener(OnFailureListener listener);
public AlicomCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

代码示例：

this.AlicomCaptcha4Client
    .addOnSuccessListener({
        async onSuccess(status: boolean, response: string) {
            if (status) {
                // TODO 开启⼆次验证
            } else {
                // TODO ⽤户答案验证错误
            }
        }
    })
    .addOnFailureListener({
        onFailure: function (error: string) {
            console.log('onFailure' + error);
        }
    })
    .addOnWebViewShowListener({
        onWebViewShow: function () {
            console.log('onWebViewShow');
        }
    });

正常加载代码示例：

onClick(() => {
    AlicomCaptcha4Config: AlicomCaptcha4Config = new AlicomCaptcha4Config()
        .setIsDebug(false) // TODO 线上务必关闭
        .setLanguage("zh")
        .setTimeOut(10000)
        .setIsCanceledOnTouchOutside(true);

    AlicomCaptcha4Client: AlicomCaptcha4Client = AlicomCaptcha4Client.getClient()
        .init("your captcha_id", config)
        .addOnSuccessListener({
            async onSuccess(status: boolean, response: string) {
                AlertDialog.show({ message: response });
                if (status) {
                    // TODO 开启⼆次验证
                } else {
                    // TODO ⽤户答案验证错误
                }
            }
        })
        .addOnFailureListener({
            onFailure: function (error: string) {
                console.log('onFailure' + error);
            }
        })
        .addOnWebViewShowListener({
            onWebViewShow: function () {
                console.log(`onWebViewShow`);
            }
        })
        .verifyWithCaptcha();
})

参数配置

通过AlicomCaptcha4Config.Builder类配置参数

定义	说明
setParams	额外的参数，会被传递到前端`JS`中使用。
setIsDebug	是否`debug`模式，默认`false`，线上请置为`false`。
setLanguage	指定语言，默认跟随应用语言。支持的语言及短码请参见多语言短码。
setIsCanceledOnTouchOutside	点击区域外是否消失，默认`true`。
setTimeOut	设置超时，单位ms，默认`10000`。
setResourcePath	设置中间地址，默认加载公共`html`文件。
setBackgroundColor	设置背景颜⾊，默认透明。
setDialogStyle	设置对话框的主题样式，默认值 `{alignment: DialogAlignment.Center}`。

可通过setParams接口配置参数，setParams接口只能接收基本数据类型、字符串、JSONArray类型的数据，详情请参见额外参数配置。

处理错误

验证过程中可能发生一些预料之外的错误，您可以通过实现addOnFailureListener接口后，在下面的回调方法中进行处理，错误回调包括用户主动取消验证，可单独过滤掉。

AlicomCaptcha4Client.addOnFailureListener({
    onFailure: function (error: string) {
        // 返回error内容示例
        // {"code":"-14460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}
        // 可对error做json解析，⾃⾏替换错误描述，保留错误码
    }
})

常见问题

调用图形认证鸿蒙客户端SDK过程中返回的错误码及其说明请参见错误码。