--- title: HarmonyOS SDK description: "CaptchaLa 鸿蒙 HarmonyOS NEXT SDK(ArkTS):从控制台下载 HAR 安装、验证流程与服务端校验。" --- # HarmonyOS SDK 面向 **HarmonyOS NEXT(API 12 / HarmonyOS 5.0.0 及以上)** 的 ArkTS SDK,以单个 `.har`(`@captchala/captchala`)分发。当前版本:**1.2.0**。验证流程与 Android、iOS SDK 一致:验证码以对话框形式弹出在当前页面之上,返回的 `passToken` 交给你的后端校验。 ::: info HarmonyOS 4.x 及更早版本运行的是 Android 应用,请改用 [Android SDK](./android)。 ::: ## 安装 SDK **没有发布到 ohpm**。请从控制台下载 HAR,再以本地依赖方式引入。 1. 登录控制台,打开 [**SDK 下载**](https://dash.captcha.la/sdk-downloads?platform=harmony)。同一页面还提供可在 DevEco Studio 中打开的鸿蒙示例工程(源码)。 2. 下载 HarmonyOS HAR,例如 `captchala-1.2.0.har`。 3. 将文件的 SHA-256 与下载页上显示的值比对,不一致时不要使用该文件。 ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. 把文件复制到 `entry/libs/`,并在 `entry/oh-package.json5` 中添加依赖: ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. 在 `entry` 目录执行 `ohpm install`,或在 DevEco Studio 中点击 **Sync Now**。 ```bash cd entry ohpm install ``` HAR 是经过混淆的 release 构建,只暴露下文列出的公开 API。使用方混淆规则已随 HAR 一起分发,你的 release 构建无需额外添加 keep 规则。 ### 权限 SDK 只使用一个权限 `ohos.permission.INTERNET`,不会申请或弹出任何运行时权限。请确认你的 entry 模块已声明: ```json5 // entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } } ``` ### 升级 下载新的 HAR 并复制到 `entry/libs/`,修改 `entry/oh-package.json5` 中 `file:` 路径里的版本号,删除旧的 `.har`,然后重新执行 `ohpm install`。 ## 快速开始 整体流程: 1. 你的后端为当前登录用户签发一次性 `server_token`(见 [Server token](#server-token))。 2. App 把它传给 SDK 并打开验证码。 3. `onSuccess` 返回 `passToken`,App 将其发送到你的后端。 4. 你的后端校验 `passToken`(见 [服务端校验](#server-side-validation))。 ```ts import { CaptchalaClient, CaptchalaConfigBuilder, CaptchalaListener, CaptchalaResult, CaptchalaError } from '@captchala/captchala'; @Entry @Component struct Login { private async verify(): Promise { // 1. Fetch a one-shot server_token from YOUR backend // (which calls the CaptchaLa server API with X-App-Key + X-App-Secret). const serverToken: string | null = await fetchServerTokenFromYourBackend(); // 2. Listen for terminal events. const listener: CaptchalaListener = { onReady: (): void => { /* challenge presented */ }, onSuccess: (result: CaptchalaResult): void => { // Send result.passToken to your backend for validation. sendToBackend(result.passToken); }, onFail: (error: CaptchalaError): void => { /* wrong answer, the user may retry */ }, onError: (error: CaptchalaError): void => { /* network / configuration error */ }, onClose: (): void => { /* user dismissed */ }, onExpired: (passToken: string): void => { /* the pass token expired: ask the user to verify again */ } }; // 3. Build the config. const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setAction('login') // login, register, pay, … // .setLang('ja') // optional: default is the device language // .setTheme('light') // optional: 'auto' (default, follows the system) | 'light' | 'dark' .setServerToken(serverToken) .setOnServerTokenExpired(() => fetchServerTokenFromYourBackend()) .build(); // 4. Open the CAPTCHA. The result is delivered through the listener. CaptchalaClient.getClient(this.getUIContext()) .init(config) .setListener(listener) .verify(); } build() { Button('Verify').onClick(() => { this.verify(); }) } } ``` ## Server token {#server-token} `server_token` 由你的后端(而不是 App)调用 `/v1/server/challenge/issue` 签发,请求带上 `X-App-Key` + `X-App-Secret`。传入 `bind_uid`(你自己系统中的用户 ID),这样 token 以及由它产生的 `passToken` 都归属于该用户: ```bash POST https://verify.captcha.la/v1/server/challenge/issue X-App-Key: YOUR_APP_KEY X-App-Secret: YOUR_APP_SECRET Content-Type: application/x-www-form-urlencoded action=login&ttl=300&max_uses=1&bind_uid=user_12345 ``` ```json { "code": 0, "data": { "server_token": "sct_xxxxxxxxxxxx", "expires_in": 300, "issued_at": 1713600000 } } ``` 把 `data.server_token`(前缀 `sct_`)返回给 App。`action` 必须与 `setAction` 传入的值一致。设置 `setOnServerTokenExpired` 后,若 token 在验证过程中被拒绝,SDK 会自动获取新 token 并重试;回调返回 `null` 则把原始错误抛给你。 身份绑定参数(`bind_uid`、`bind_ip`)只在你的服务端签发 token 时设置,App 不会发送这些参数。完整参数见 [API 参考](../api-reference#server-token),也可以直接使用 [PHP](./server-php) / [Go](./server-go) 服务端 SDK。 ## API 一览 {#api-surface} | 符号 | 用途 | | --- | --- | | `CaptchalaClient.getClient(uiContext)` | 单例入口,绑定到当前页面的 `UIContext`。 | | `CaptchalaConfigBuilder` | 链式配置构建器(见下表),`build()` 返回 `CaptchalaConfig`。 | | `init(config)` | 应用配置,返回 client 本身,便于链式调用。 | | `setListener(listener)` | 注册 `CaptchalaListener`。只有 `onSuccess` 必填,`onReady`、`onFail`、`onError`、`onClose` 和 `onExpired`(见 [Token 过期](#token-expiry))可选。 | | `verify()` | 打开验证码对话框,结果通过 listener 回调。 | | `refresh()` / `cancel()` / `dismiss()` | 刷新当前题目 / 终止流程并关闭对话框 / 关闭对话框。 | | `setServerToken(token)` | 替换 server token:下一次 ticket 请求使用它,取代配置中的 token 或 provider 之前返回的 token。可在 `verify()` 之前或两次调用之间、从任意线程调用,本身不会发起验证。空 token 会被忽略;`init(config)` 会恢复为配置中的 token。 | | `getLastError()` | 当前或上一次验证的最近一个 `CaptchalaError`,没有时为 `null`。`verify()` 开始时和验证通过时清空。 | | `CaptchalaClient.destroy()` | 释放单例。 | | `CaptchalaResult` | `passToken`、`challengeId`、`ttl`、`isOffline`、`isClientOnly`。把 `passToken` 发到你的后端。`ttl` 自 1.2.0 起已弃用:token 有效期由服务端决定,且可能调整;请改用 `onExpired`。 | | `CaptchalaError` | `code`、`message`、`detail`,以及错误字段 `errorClass`、`retryable`、`retryAfter`、`reason`、`attempt`、`willRetry`。传给 `onFail`(用户可重试)和 `onError`(网络、配置或系统错误)。 | ```ts const client = CaptchalaClient.getClient(this.getUIContext()); client.refresh(); // reload the current challenge client.cancel(); // stop the flow and close the dialog client.dismiss(); // close the dialog CaptchalaClient.destroy(); // release the singleton ``` ### 配置项 {#configuration} | 方法 | 默认值 | 说明 | | --- | --- | --- | | `setAppKey(string)` | 必填 | 控制台中的 App Key。 | | `setAction(string)` | `default` | 业务场景(`login`、`register`、`pay` 等),须与 `server_token` 的 action 一致。 | | `setLang(string)` | `''` (auto) | 验证码语言,如 `en`、`zh-CN`。 | | `setTheme(string)` | `auto` | `auto`(跟随系统)、`light` 或 `dark`。 | | `setCornerRadius(number)` | `12` | 弹窗圆角(vp),`0` 为直角;页面和加载骨架屏都按此圆角裁剪。 | | `setTitle(string \| null)` | `null` | 在 HarmonyOS 上无效:弹窗没有标题栏(验证码自带标题)。只用于 macOS / 桌面端窗口标题。 | | `setServerToken(string \| null)` | `null` | 你的后端签发的 `server_token`。 | | `setOnServerTokenExpired(cb)` | `null` | `() => Promise`,从你的后端获取新的 `server_token`。 | | `setTimeout(number)` | `10000` | 请求超时(毫秒)。 | | `setEnableVoice(boolean)` | `true` | 提供语音验证选项。 | | `setEnableOfflineMode(boolean)` | `false` | 允许故障降级,其结果带 `isOffline` / `isClientOnly` 标记。 | | `setMaskClosable(boolean)` | `false` | 点击遮罩关闭对话框。 | | `setAccount(string \| null)` | `null` | 可选的账号标识。 | | `setRetryCount(number)` | `3` | 连接尝试次数。 | | `setRetryDelay(number)` | `1000` | 重试间隔(毫秒)。 | | `setBypassServers(string[] \| null)` | `null` | 自定义离线兜底主机。 | | `setCollectOdid(boolean)` | `true` | 上报设备 ODID 的哈希(见 [隐私](#privacy))。 | | `setLoadingStyle(string)` | `'spinner'` | 加载指示器,见[加载指示器](#loading-indicator)。 | | `setLoadingColor(string \| null)` | 白色 | 指示器颜色,`#RRGGBB` 或 `#RRGGBBAA`。 | | `setLoadingSize(string)` | `'medium'` | `'small'`、`'medium'` 或 `'large'`。 | | `setLoadingDelay(number)` | `300` | 指示器出现前的等待毫秒数,`0`–`5000`。 | | `setDebug(boolean)` | `false` | 开发阶段输出详细日志。 | ## 行为说明 - **在 `verify()` 之前设置 server token。** 请在 `init(config)` 之前在构建器上调用 `setServerToken()`。 之后要换新 token,可在下一次 `verify()` 之前调用 `client.setServerToken(token)`,或由 `setOnServerTokenExpired` 提供;重新调用 `init()` 也可以。 - **语言。** `setLang` 为空(默认)即自动:取 App / 设备语言映射到 54 种支持的语言,都不匹配时用英文。 - **`cancel()` 只触发一次 `onClose`**(验证进行中或弹窗显示时),不会再有错误回调或迟到的结果。 - **同一时间只有一次验证。** 验证进行中或弹窗显示期间再次调用 `verify()` 会被忽略,每次验证只有一个结果。 ## Token 过期 {#token-expiry} `onSuccess` 返回的 pass token 有效期有限,由服务端决定。如果页面在此之前还没用掉它, listener 的 `onExpired(passToken)` 会被调用一次,你可以借此清除保存的 token 并提示用户重新验证, 而不是提交一个已过期的 token。用 `verify()` 发起新的验证。 ```ts const listener: CaptchalaListener = { onSuccess: (result: CaptchalaResult): void => { this.passToken = result.passToken; }, onExpired: (passToken: string): void => { this.passToken = ''; this.showVerifyAgain = true; // your button calls client.verify() again } }; ``` 发起新的 `verify()`、调用 `init()` 或 `destroy()` 之后,不会再调用 `onExpired`。 1.2.0 起可用。 ## 加载指示器 {#loading-indicator} 挑战加载期间,SDK 会在遮罩上显示一个小的加载指示器。只有加载时间超过 `setLoadingDelay`(默认 300 ms)时才会出现, 挑战显示后即消失。1.2.0 起可用。 - `setLoadingStyle`:`'spinner'`(默认,辐条)、`'ring'`(旋转的圆弧)、`'dots'` 或 `'none'`。 设为 `'none'` 时不显示任何内容:请在 `verify()` 到 `onReady` 之间显示你自己的指示器。 - `setLoadingColor`:`#RRGGBB` 或 `#RRGGBBAA`,默认白色。 - `setLoadingSize`:`'small'`、`'medium'`(默认)或 `'large'`。 - `setLoadingDelay`:毫秒,`0`–`5000`。 ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## ArkGuard(代码混淆) HAR 自带的 consumer rules 保证 SDK 公开 API 在你混淆后的 release 包中正常可用。如果你的 App 开启了**属性混淆**(`-enable-property-obfuscation`),ArkGuard 也会重命名**你自己代码**里的属性名, 用点号读取 JSON(例如后端响应的 `body.server_token`)可能失效。请用字符串 key 读取,或保留这些名字: ```ts const body: Record = JSON.parse(text) as Record; const token = body['server_token'] as string; // string key: not renamed ``` ```text # obfuscation-rules.txt (alternative) -keep-property-name server_token ``` ## 错误处理与重试 选项(全部可选,不设置时保持原有行为):`setRetry`、`setRetryInterval`、`setRetryMax`(连接尝试次数,同 `setRetryCount`)、`setRetryBackoff`、`setOfflineFallback`(同 `setEnableOfflineMode`)、`setRefreshExpired`、`setServerTokenProvider`(优先于 `setOnServerTokenExpired`,10 秒超时)。 错误字段:`CaptchalaError.errorClass`(`config`、`rate_limit`、`blocked`、`subscription`、`server_token`、`business`、`network`、`clock_skew`,与 Web SDK 分类相同)、`retryable`、`retryAfter`(秒或 `null`)、`reason`、`attempt`(本次验证的 ticket 请求次数,1 为第一次)和 `willRetry`(SDK 会自行继续时为 `true`)。`client.getLastError()` 返回最近一次错误;`client.setServerToken(token)` 替换下一次请求使用的 server token。 ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setRetry('auto') // 'legacy' (default) | 'auto' | 'never' .setServerTokenProvider(async (): Promise => fetchServerTokenFromYourBackend()) .setRefreshExpired('auto') .build(); const listener: CaptchalaListener = { onSuccess: (result: CaptchalaResult): void => { /* … */ }, onError: (error: CaptchalaError): void => { if (error.retryAfter !== null) { showWaitHint(error.retryAfter); } // rate limit else if (!error.retryable) { showSupportHint(error.code); } // config, blocked, binding else { showRetryButton(); } // verify() again later } }; ``` - **离线兜底默认失败即关闭(fail-closed)。** `offlineFallback` 跟随 `enableOfflineMode`(`false`): 故障以错误结束,绝不会离线通过或给出 client-only 结果。 - **限流。** HTTP 429 以错误上报,错误类为 `rate_limit`,带 `retryable` 和 `retryAfter`(秒);默认不重试。`retry` 为 `auto` 时,若等待不超过 60 秒, SDK 会在 `retryAfter` 之后重试一次。 错误分类与建议处理见[错误处理与重试](../concepts/handling-errors)。 ## 更快显示首个挑战 - `setPrewarm(true)`(默认)会在 `init()` 时预热 API 连接和验证页。请在页面出现时(`aboutToAppear`)调用 `init()`,不要只在点击时调用。 - 在页面出现时从你的后端获取 server token 并缓存,点击时直接使用;只有缺失或过期时才在点击时获取。 - 1.1.0 起首个挑战无需额外请求即可显示:页面直接使用 SDK 已收到的应答渲染。 ## 服务端校验 {#server-side-validation} 把 `result.passToken` 转发到你的后端,由后端调用 CaptchaLa API 校验。切勿把 `X-App-Secret` 放进 App。 ```bash POST https://verify.captcha.la/v1/validate X-App-Key: YOUR_APP_KEY X-App-Secret: YOUR_APP_SECRET Content-Type: application/json { "pass_token": "", "expected_action": "login" } ``` 仅当 `data.valid` 为 `true` 且 `data.uid` 等于你签发 `server_token` 时绑定的用户时才放行。token 只能使用一次。完整响应与错误码见 [API 参考](../api-reference)。 ## 隐私 {#privacy} SDK 读取一组无需权限的设备属性(机型、系统版本、屏幕、语言、时区等),仅用于验证和反欺诈。默认还会上报设备 ODID 的截断 SHA-256 哈希,从不上报原始值。不采集 OAID、UDID、序列号或账号数据。关闭 ODID 哈希: ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setCollectOdid(false) // the ODID is never read .build(); ``` 如果保持开启,请在隐私政策和 AppGallery 隐私标签中声明“用于反欺诈的设备标识符”。 在操作系统允许的情况下,SDK 会上报设备的本地网络地址及网络接口硬件地址(MAC),用于反欺诈。它们只在加密请求中发送,从不写入日志;CaptchaLa 完整保留较短时间(默认 7 天),之后只保留截断形式(IPv4 /24、IPv6 /48、MAC 厂商前缀)。 ## 常见问题 {#troubleshooting} - **`ohpm install` 找不到包** `file:` 路径相对于 `entry` 模块。确认文件位于 `entry/libs/`,且 `oh-package.json5` 中的文件名与之完全一致。 - **升级后仍在使用旧版本** 从 `entry/libs/` 删除旧的 `.har`,更新 `file:` 路径中的版本号,再执行 `ohpm install`(或 **Sync Now**)。 - **SHA-256 不一致** 从 [**SDK 下载**](https://dash.captcha.la/sdk-downloads?platform=harmony) 重新下载 HAR。校验值与控制台不一致的文件不要发布。 - **`onError` 返回 `server_token_*` 错误码** 检查 App 的 `setAction` 是否与签发 token 时的 `action` 一致,以及 `setOnServerTokenExpired` 是否返回了新的 token。 - **设备运行 HarmonyOS 4.x 或更早版本** 不支持。这类设备运行 Android 应用,请使用 [Android SDK](./android)。 ## 环境要求 {#requirements} - HarmonyOS NEXT,API 12(HarmonyOS 5.0.0)及以上,Stage 模型 - 设备类型:手机、平板、2in1 - ABI:`arm64-v8a`、`x86_64`(模拟器) - `ohos.permission.INTERNET`