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:
| Component | Role | Data passed |
|---|---|---|
| HTML5 client | Renders the Captcha widget; calls the native interface on success | captchaVerifyParam token |
| HarmonyOS Next app | Hosts the HTML5 page in a Web component; exposes testInterface to JavaScript | Token forwarded to backend |
| Backend server | Calls VerifyIntelligentCaptcha to confirm the result server-side | Verification outcome |
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:
Activated the Alibaba Cloud Captcha V2.0 service
Created a verification scenario with Integration Method set to Webview+H5 (for Apps/WeChat Mini Programs)
DevEco Studio 5.0.3.403 or later
HarmonyOS SDK API Level 12 or later
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.
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:
The Captcha widget renders correctly inside the app.
After a successful challenge,
getCaptchaVerifyParamis called with a non-empty token.Your backend server receives the token and
VerifyIntelligentCaptchareturns a successful result.
What's next
Web and H5 client integration (V3 architecture) — Full HTML5 client setup reference
Server-side integration — Backend SDK setup and
VerifyIntelligentCaptchaAPI reference