Overview and Resources

The behavior verification HarmonyOS Next SDK is provided for developers integrating the HarmonyOS Next native client.

Environmental Requirements

Related Resources

1
/
). |

Installation

Integrating SDK

Manual Download Integration

Download the .zip file from the SDK resource package link to get the latest sdk.

Import SDK

Drag the .har file (including geetest_captcha_harmonyos_vx.y.z_date.har) from the zip package into the libs folder in your project. After dragging the .har file into the libs folder, check if the .har has been added to Library. Add the following code to oh-package.json5 in your project:

"dependencies": {
    "captchaSdk": "file:./libs/geetest_captcha_harmonyos_vx.y.z_date.har"
}

Adding Permissions

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

Obfuscation Rules

The GeeTest SDK has been obfuscated. When integrating, please include the obfuscation rules and do not obfuscate the SDK again.

Configuring Interfaces

Call Logic

1. Configure Initialization
2. Start Verification
3. Get Verification Callback
4. Destroy Resources

As shown in the product workflow process, you need to set up Server interface in your backend first,
and configure it with captchaId and Key
you got from GeeTest dashbaord.

Initialization

The SDK initialization configuration can be done in the onCreate or onCreateView methods.

Method Description

public static getClient(context: UIContext): GTCaptcha4Client;
public init(captchaId: string, config?: GTCaptcha4Config): GTCaptcha4Client;

Parameter Description

Start Verification

Start the verification process.

Method Description

public void verifyWithCaptcha();

Cancel Verification

Cancel the verification process and close the verification window.

Method Description

public void cancel();

Enable/Disable Log Monitoring

Set to enable or disable log monitoring.

Method Description

public void setLogEnable(enable: boolean);

Get Verification Callback

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

Code Example

this.gtCaptcha4Client.addOnSuccessListener({
  async onSuccess(status: boolean, response: string) {
    if(status){
      // TODO Start secondary verification
    }else {
      // TODO User answer verification failed
    }
  }
})
  .addOnFailureListener({
    onFailure: function (error: string) {
      console.log('onFailure' + error);
    }
  })
  .addOnWebViewShowListener({
    onWebViewShow: function () {
      console.log(`onWebViewShow`);
    }
  })

Normal Loading Code Example

onClick(() => {
    gtCaptcha4Config: GTCaptcha4Config = new GTCaptcha4Config()
        .setIsDebug(false) // TODO Disable in production
        .setLanguage("zh")
        .setTimeOut(10000)
        .setIsCanceledOnTouchOutside(true);
    gtCaptcha4Client: GTCaptcha4Client = GTCaptcha4Client.getClient()
        .init("your captcha_id", config)
        .addOnSuccessListener({
        async onSuccess(status: boolean, response: string) {
          AlertDialog.show({ message: response })
            if(status){
                // TODO Start secondary verification
            }else {
                // TODO User answer verification failed
            }
        }
      })
       .addOnFailureListener({
         onFailure: function (error: string) {
           console.log('onFailure' + error);
         }
      })
       .addOnWebViewShowListener({
         onWebViewShow: function () {
           console.log(`onWebViewShow`);
         }
      })
       .verifyWithCaptcha();
})

Refer to the official demo for detailed example code

Parameter Configuration

Configure parameters using the GTCaptcha4Config.Builder class.

Parameters can be configured using the setParams interface, see the interface documentation for details.

The setParams interface can only receive basic data types, strings, and JSONArray data.

Handling Errors

Unexpected errors may occur during verification. You can handle them by implementing the addOnFailureListener interface and handling them in the following callback method:

Note: The error callback includes user-initiated verification cancellations, which can be filtered separately.

gtCaptcha4Client.addOnFailureListener({
  onFailure: function (error: string) {
    // Example error content
    // {"code":"-14460","msg":"Verification session has been canceled","desc":{"description":"User cancelled 'Captcha'"}}
    // You can parse the error as JSON and replace the error description while keeping the error code
  }
})

It is strongly recommended to present both an error message and error code to the end user. This will facilitate subsequent troubleshooting.

Please refer to the following list for possible error codes: Error Code List