--- title: HarmonyOS SDK description: "CaptchaLa 鴻蒙 HarmonyOS NEXT SDK(ArkTS):從控制台下載 HAR 安裝、驗證流程與伺服器端驗證。" --- # HarmonyOS SDK ::: info SDK 1.2.0 已針對 SDK 1.2.0 更新。部分細節僅提供英文版:請參閱[英文頁面](/sdk/harmony)與[更新日誌](/changelog#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](./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()` | 重新整理目前題目 / 終止流程並關閉對話框 / 關閉對話框。 | | `CaptchalaClient.destroy()` | 釋放單例。 | | `CaptchalaResult` | `passToken`、`challengeId`、`ttl`、`isOffline`、`isClientOnly`。將 `passToken` 送到你的後端。`ttl` 自 1.2.0 起已棄用:token 有效期由伺服器決定且可能調整,請改用 `onExpired`。 | | `CaptchalaError` | `code`、`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 ``` ### 設定項目 {#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`。 | | `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` | 點擊遮罩即可關閉對話框。 | | `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` | 開發階段輸出詳細日誌。 | ## 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 毫秒)才會出現,驗證題顯示後即消失。自 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(); ``` ## 伺服器端驗證 {#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 隱私標籤中宣告「用於防詐的裝置識別碼」。 ## 常見問題 {#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`