HarmonyOS client integration

Environment requirements

Download the SDK

Log on to the Phone Number Verification Service console. On the Overview page, locate the API&SDK section and click Download Now. On the API&SDK page, download and decompress the SDK package as instructed.

Import the SDK

1. Create or open your project in DevEco Studio.

2. Decompress the downloaded SDK package. Copy the .har file to the libs directory of your project.

3. Add the SDK dependency to the oh-package.json5 file of your project:

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

Add permission configurations

Edit the module.json5 file to configure the required SDK permissions:

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

Obfuscation rules

The Captcha SDK is already obfuscated. When you integrate the SDK, include the obfuscation rules but do not obfuscate the SDK again.

Create a verification plan

To use the SDK, you need key parameters. First, go to the Captcha Plan Management console to create a Captcha plan. Then, obtain the key parameters, which include the appId and appKey.

Initialization

Configure the SDK initialization. You can initialize the SDK in the onCreate or onCreateView method.

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

Start verification

Starts the verification flow.

public void verifyWithCaptcha();

Cancel verification

Cancels the verification flow and closes the verification window.

public void cancel();

Enable or disable log monitoring

Enables or disables log printing.

public void setLogEnable(enable: boolean);

Get verification callbacks

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

Code example:

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

Normal load code example:

onClick(() => {
    AlicomCaptcha4Config: AlicomCaptcha4Config = new AlicomCaptcha4Config()
        .setIsDebug(false) // TODO: Make sure to disable this in the production environment.
        .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: Enable secondary verification.
                } else {
                    // TODO: User answer verification failed.
                }
            }
        })
        .addOnFailureListener({
            onFailure: function (error: string) {
                console.log('onFailure' + error);
            }
        })
        .addOnWebViewShowListener({
            onWebViewShow: function () {
                console.log(`onWebViewShow`);
            }
        })
        .verifyWithCaptcha();
})

Handle errors

Unexpected errors can occur during verification. You can handle them in the callback method after you implement the addOnFailureListener interface. This error callback is also triggered when a user manually cancels the verification, which you can filter out as a specific case.

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

For a list of error codes that are returned when you call the Captcha HarmonyOS client SDK and their descriptions, see Error codes.