All Products
Search
Document Center

Captcha:Integrate Alibaba Cloud Captcha V2.0 (V3 architecture) with HarmonyOS Next

Last Updated:Mar 31, 2026

Alibaba Cloud Captcha V2.0 uses a mobile HTML5 page loaded inside a WebView to run human verification in your HarmonyOS Next app. This approach avoids native-component dependency issues and lets the Captcha service iterate independently of your app release cycle.

How it works

The integration connects three components along a single verification chain:

ComponentRoleData passed
HTML5 clientRenders the Captcha widget; calls the native interface on successcaptchaVerifyParam token
HarmonyOS Next appHosts the HTML5 page in a Web component; exposes testInterface to JavaScriptToken forwarded to backend
Backend serverCalls VerifyIntelligentCaptcha to confirm the result server-sideVerification outcome
Important

The server-side verification step is mandatory. Skipping it lets attackers forge verification results, which makes the CAPTCHA protection ineffective.

A complete working sample is available: HarmonyOS Next demo. Download it before you start to use as a reference while following this guide.

Prerequisites

Before you begin, make sure you have:

Step 1: Set up the HTML5 client

Follow the Web and H5 client integration (V3 architecture) guide to embed Captcha V2.0 in your HTML5 page.

In the success callback, pass captchaVerifyParam to the native HarmonyOS interface registered in Step 3:

// Called when Captcha verification succeeds
function success(captchaVerifyParam) {
    console.log('Verification successful:', captchaVerifyParam);
    // Send the token to the native HarmonyOS interface
    window.testInterface && window.testInterface.getCaptchaVerifyParam(captchaVerifyParam);
}

The Captcha server validates the user interaction and returns the Captcha code and other parameters to the client.

Step 2: Set up the backend server

Integrate the Captcha V2.0 server-side software development kit (SDK) in your backend, then call the VerifyIntelligentCaptcha API to verify the token received from the app. For setup instructions, see Server-side integration.

Important

Always perform this server-side verification step. Without it, attackers can forge verification results and bypass CAPTCHA protection entirely.

Step 3: Configure the HarmonyOS Next app

Add network permissions

In entry/src/main/module.json5, add the following permissions under requestPermissions:

{
  "module": {
    // ...other configurations
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO"
      }
    ]
  }
}

Create the JavaScript interface class

Define a class that receives the verification token from JavaScript:

class JSInterface {
  // Method to accept the signature verification parameters
  getCaptchaVerifyParam(captchaVerifyParam: string): void {
    console.info('Received signature verification parameters:', captchaVerifyParam);
    // Here, you can send the verification parameters to the backend for signature verification.
    // Example: sendVerifyParamToServer(captchaVerifyParam);
  }
}

Build the Captcha page component

In entry/src/main/ets/pages/Index.ets, create a page that loads the HTML5 Captcha page inside a Web component and registers the JavaScript interface after the page loads:

import { webview } from '@kit.ArkWeb';
import { router } from '@kit.ArkUI';

class JSInterface {
  getCaptchaVerifyParam(captchaVerifyParam: string): void {
    console.info('Received signature verification parameters:', captchaVerifyParam);
    // Here, you can send the verification parameters to the backend for signature verification.
  }
}

@Entry
@Component
struct Index {
  private webviewController: webview.WebviewController = new webview.WebviewController();
  private jsInterface = new JSInterface();

  build() {
    Column() {
      // Load the Captcha HTML page using the Web component
      Web({ src: $rawfile('captcha.html'), controller: this.webviewController })
        .javaScriptAccess(true)
        .domStorageAccess(true)
        .onlineImageAccess(true)
        .mixedMode(MixedMode.All)
        .cacheMode(CacheMode.None)
        .onPageEnd((event) => {
          // Register the JavaScript interface after the page finishes loading
          try {
            this.webviewController.registerJavaScriptProxy(
              this.jsInterface,
              "testInterface",               // Must match window.testInterface in your HTML
              ["getCaptchaVerifyParam"]       // Methods exposed to JavaScript
            );
            console.info('JavaScript interface registered successfully');
          } catch (error) {
            console.error('Failed to register the JavaScript interface:', error);
          }
        })
        .width('100%')
        .height('100%')
    }
  }
}

The registerJavaScriptProxy call creates the bridge between JavaScript and ArkTS. The interface name "testInterface" must match window.testInterface in your HTML5 page.

Verify the integration

Run the app on a HarmonyOS Next device or emulator. Trigger the Captcha widget and confirm that:

  1. The Captcha widget renders correctly inside the app.

  2. After a successful challenge, getCaptchaVerifyParam is called with a non-empty token.

  3. Your backend server receives the token and VerifyIntelligentCaptcha returns a successful result.

What's next