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。
安装
SDK 没有发布到 ohpm。请从控制台下载 HAR,再以本地依赖方式引入。
- 登录控制台,打开 SDK 下载。同一页面还提供可在 DevEco Studio 中打开的鸿蒙示例工程(源码)。
- 下载 HarmonyOS HAR,例如
captchala-1.2.0.har。 - 将文件的 SHA-256 与下载页上显示的值比对,不一致时不要使用该文件。
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- 把文件复制到
entry/libs/,并在entry/oh-package.json5中添加依赖:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}- 在
entry目录执行ohpm install,或在 DevEco Studio 中点击 Sync Now。
cd entry
ohpm installHAR 是经过混淆的 release 构建,只暴露下文列出的公开 API。使用方混淆规则已随 HAR 一起分发,你的 release 构建无需额外添加 keep 规则。
权限
SDK 只使用一个权限 ohos.permission.INTERNET,不会申请或弹出任何运行时权限。请确认你的 entry 模块已声明:
// entry/src/main/module.json5
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" }
]
}
}升级
下载新的 HAR 并复制到 entry/libs/,修改 entry/oh-package.json5 中 file: 路径里的版本号,删除旧的 .har,然后重新执行 ohpm install。
快速开始
整体流程:
- 你的后端为当前登录用户签发一次性
server_token(见 Server token)。 - App 把它传给 SDK 并打开验证码。
onSuccess返回passToken,App 将其发送到你的后端。- 你的后端校验
passToken(见 服务端校验)。
import {
CaptchalaClient,
CaptchalaConfigBuilder,
CaptchalaListener,
CaptchalaResult,
CaptchalaError
} from '@captchala/captchala';
@Entry
@Component
struct Login {
private async verify(): Promise<void> {
// 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 由你的后端(而不是 App)调用 /v1/server/challenge/issue 签发,请求带上 X-App-Key + X-App-Secret。传入 bind_uid(你自己系统中的用户 ID),这样 token 以及由它产生的 passToken 都归属于该用户:
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{
"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 参考,也可以直接使用 PHP / Go 服务端 SDK。
API 一览
| 符号 | 用途 |
|---|---|
CaptchalaClient.getClient(uiContext) | 单例入口,绑定到当前页面的 UIContext。 |
CaptchalaConfigBuilder | 链式配置构建器(见下表),build() 返回 CaptchalaConfig。 |
init(config) | 应用配置,返回 client 本身,便于链式调用。 |
setListener(listener) | 注册 CaptchalaListener。只有 onSuccess 必填,onReady、onFail、onError、onClose 和 onExpired(见 Token 过期)可选。 |
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(网络、配置或系统错误)。 |
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配置项
| 方法 | 默认值 | 说明 |
|---|---|---|
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<string | null>,从你的后端获取新的 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 的哈希(见 隐私)。 |
setLoadingStyle(string) | 'spinner' | 加载指示器,见加载指示器。 |
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 过期
onSuccess 返回的 pass token 有效期有限,由服务端决定。如果页面在此之前还没用掉它, listener 的 onExpired(passToken) 会被调用一次,你可以借此清除保存的 token 并提示用户重新验证, 而不是提交一个已过期的 token。用 verify() 发起新的验证。
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 起可用。
加载指示器
挑战加载期间,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。
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 读取,或保留这些名字:
const body: Record<string, Object> = JSON.parse(text) as Record<string, Object>;
const token = body['server_token'] as string; // string key: not renamed# 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。
const config = new CaptchalaConfigBuilder()
.setAppKey('YOUR_APP_KEY')
.setRetry('auto') // 'legacy' (default) | 'auto' | 'never'
.setServerTokenProvider(async (): Promise<string | null> => 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之后重试一次。
错误分类与建议处理见错误处理与重试。
更快显示首个挑战
setPrewarm(true)(默认)会在init()时预热 API 连接和验证页。请在页面出现时(aboutToAppear)调用init(),不要只在点击时调用。- 在页面出现时从你的后端获取 server token 并缓存,点击时直接使用;只有缺失或过期时才在点击时获取。
- 1.1.0 起首个挑战无需额外请求即可显示:页面直接使用 SDK 已收到的应答渲染。
服务端校验
把 result.passToken 转发到你的后端,由后端调用 CaptchaLa API 校验。切勿把 X-App-Secret 放进 App。
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": "<result.passToken>", "expected_action": "login" }仅当 data.valid 为 true 且 data.uid 等于你签发 server_token 时绑定的用户时才放行。token 只能使用一次。完整响应与错误码见 API 参考。
隐私
SDK 读取一组无需权限的设备属性(机型、系统版本、屏幕、语言、时区等),仅用于验证和反欺诈。默认还会上报设备 ODID 的截断 SHA-256 哈希,从不上报原始值。不采集 OAID、UDID、序列号或账号数据。关闭 ODID 哈希:
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 厂商前缀)。
常见问题
ohpm install找不到包file:路径相对于entry模块。确认文件位于entry/libs/,且oh-package.json5中的文件名与之完全一致。升级后仍在使用旧版本
从entry/libs/删除旧的.har,更新file:路径中的版本号,再执行ohpm install(或 Sync Now)。SHA-256 不一致
从 SDK 下载 重新下载 HAR。校验值与控制台不一致的文件不要发布。onError返回server_token_*错误码
检查 App 的setAction是否与签发 token 时的action一致,以及setOnServerTokenExpired是否返回了新的 token。设备运行 HarmonyOS 4.x 或更早版本
不支持。这类设备运行 Android 应用,请使用 Android SDK。
环境要求
- HarmonyOS NEXT,API 12(HarmonyOS 5.0.0)及以上,Stage 模型
- 设备类型:手机、平板、2in1
- ABI:
arm64-v8a、x86_64(模拟器) ohos.permission.INTERNET