Skip to content

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,再以本地依赖方式引入。

  1. 登录控制台,打开 SDK 下载。同一页面还提供可在 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
  1. 把文件复制到 entry/libs/,并在 entry/oh-package.json5 中添加依赖:
json5
// entry/oh-package.json5
{
  "dependencies": {
    "@captchala/captchala": "file:./libs/captchala-1.2.0.har"
  }
}
  1. 在 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)。
  2. App 把它传给 SDK 并打开验证码。
  3. onSuccess 返回 passToken,App 将其发送到你的后端。
  4. 你的后端校验 passToken(见 服务端校验)。
ts
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 都归属于该用户:

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 参考,也可以直接使用 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()释放单例。
CaptchalaResultpassToken、challengeId、ttl、isOffline、isClientOnly。把 passToken 发到你的后端。ttl 自 1.2.0 起已弃用:token 有效期由服务端决定,且可能调整;请改用 onExpired。
CaptchalaErrorcode、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

配置项 ​

方法默认值说明
setAppKey(string)必填控制台中的 App Key。
setAction(string)default业务场景(login、register、pay 等),须与 server_token 的 action 一致。
setLang(string)'' (auto)验证码语言,如 en、zh-CN。
setTheme(string)autoauto(跟随系统)、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() 发起新的验证。

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 起可用。

加载指示器 ​

挑战加载期间,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<string, Object> = JSON.parse(text) as Record<string, Object>;
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<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。

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": "<result.passToken>", "expected_action": "login" }

仅当 data.valid 为 true 且 data.uid 等于你签发 server_token 时绑定的用户时才放行。token 只能使用一次。完整响应与错误码见 API 参考。

隐私 ​

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 厂商前缀)。

常见问题 ​

  • 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

MIT-licensed examples · CaptchaLa is operated independently