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() | 重新整理目前題目 / 終止流程並關閉對話框 / 關閉對話框。 |
CaptchalaClient.destroy() | 釋放單例。 |
CaptchalaResult | passToken、challengeId、ttl、isOffline、isClientOnly。將 passToken 送到你的後端。ttl 自 1.2.0 起已棄用:token 有效期由伺服器決定且可能調整,請改用 onExpired。 |
CaptchalaError | code、message、detail。傳給 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。 |
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() 開始新的驗證。
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。
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。
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 隱私標籤中宣告「用於防詐的裝置識別碼」。
常見問題
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