Skip to content

HarmonyOS SDK ​

SDK 1.2.0

已針對 SDK 1.2.0 更新。部分細節僅提供英文版:請參閱英文頁面與更新日誌。

適用於 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()重新整理目前題目 / 終止流程並關閉對話框 / 關閉對話框。
CaptchalaClient.destroy()釋放單例。
CaptchalaResultpassToken、challengeId、ttl、isOffline、isClientOnly。將 passToken 送到你的後端。ttl 自 1.2.0 起已棄用:token 有效期由伺服器決定且可能調整,請改用 onExpired。
CaptchalaErrorcode、message、detail。傳給 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。
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點擊遮罩即可關閉對話框。
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開發階段輸出詳細日誌。

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 毫秒)才會出現,驗證題顯示後即消失。自 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();

伺服器端驗證 ​

將 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 隱私標籤中宣告「用於防詐的裝置識別碼」。

常見問題 ​

  • 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