HarmonyOS SDK
HarmonyOS NEXT(API 12 / HarmonyOS 5.0.0 以降) 向けの ArkTS SDK です。単一の .har(@captchala/captchala)として配布されます。現在のバージョン: 1.2.0。検証フローは Android / iOS SDK と同じで、CAPTCHA は現在のページの上にダイアログとして表示され、返される passToken をバックエンドで検証します。
INFO
HarmonyOS 4.x 以前は Android アプリが動作する環境です。その場合は Android SDK を使用してください。
インストール
SDK は ohpm では公開されていません。ダッシュボードから HAR をダウンロードし、ローカル依存として追加します。
- ダッシュボードにサインインし、SDK ダウンロード を開きます。同じページで、DevEco Studio で開ける HarmonyOS のデモプロジェクト(ソース)も入手できます。
- 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 は難読化済みのリリースビルドで、以下に記載する公開 API だけを公開しています。利用側の難読化ルールは HAR に同梱されているため、リリースビルドで keep ルールを追加する必要はありません。
権限
SDK が使う権限は ohos.permission.INTERNET の 1 つだけで、実行時権限の要求やダイアログ表示は一切行いません。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 を参照)。 - アプリがそれを SDK に渡して CAPTCHA を開きます。
onSuccessがpassTokenを返し、アプリはそれをバックエンドへ送ります。- バックエンドが
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 はアプリではなくバックエンドが、X-App-Key + X-App-Secret を付けて /v1/server/challenge/issue を呼び出して発行します。自社のユーザー ID を bind_uid に渡すと、トークンとそこから得られる 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_)をアプリに返します。action は setAction に渡した値と一致している必要があります。setOnServerTokenExpired を設定しておくと、チャレンジ中にトークンが拒否されたとき SDK が自動で新しいトークンを取得して再試行します。null を返すと元のエラーがそのまま通知されます。
本人紐付けのオプション(bind_uid、bind_ip)はトークン発行時にサーバー側でのみ指定します。アプリから送ることはありません。全パラメーターは API リファレンス を参照するか、PHP / Go のサーバー SDK を使用してください。
主な API
| シンボル | 用途 |
|---|---|
CaptchalaClient.getClient(uiContext) | シングルトンのエントリーポイント。ページの UIContext に紐付きます。 |
CaptchalaConfigBuilder | 設定用のビルダー(下表参照)。build() は CaptchalaConfig を返します。 |
init(config) | 設定を適用します。client を返すのでメソッドチェーンできます。 |
setListener(listener) | CaptchalaListener を登録します。必須は onSuccess のみで、onReady、onFail、onError、onClose、onExpired(トークンの有効期限を参照)は任意です。 |
verify() | CAPTCHA ダイアログを開きます。結果は listener に通知されます。 |
refresh() / cancel() / dismiss() | 現在のチャレンジを再読み込み / フローを中止してダイアログを閉じる / ダイアログを閉じる。 |
CaptchalaClient.destroy() | シングルトンを解放します。 |
CaptchalaResult | passToken、challengeId、ttl、isOffline、isClientOnly。passToken をバックエンドへ送ります。ttl は 1.2.0 で非推奨になりました。トークンの有効期間はサーバーが決め、変更されることがあるため、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 | バックエンドから新しい server_token を取得する () => Promise<string | null>。 |
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 | 開発時の詳細ログ。 |
トークンの有効期限
onSuccess で受け取る pass token の有効期間には限りがあり、その長さはサーバーが決めます。期限までにページで使われなかった場合、listener の onExpired(passToken) が 1 回呼ばれます。保存したトークンを破棄し、期限切れのトークンを送信する代わりにユーザーへ再検証を促してください。新しい検証は 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();サーバー側検証
result.passToken をバックエンドに転送し、CaptchaLa API で検証します。X-App-Secret は決してアプリに含めないでください。
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 を発行したユーザーと一致する場合にのみリクエストを受け付けます。トークンは 1 回限りです。レスポンス全体とエラーコードは API リファレンス を参照してください。
プライバシー
SDK は権限不要の端末属性(機種、OS バージョン、画面、ロケール、タイムゾーンなど)を読み取り、検証と不正防止にのみ使用します。既定では端末 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_*コードが返る
アプリのsetActionがトークン発行時のactionと一致しているか、setOnServerTokenExpiredが新しいトークンを返しているかを確認してください。端末が HarmonyOS 4.x 以前
非対応です。これらの端末では Android アプリが動作するため、Android SDK を使用してください。
動作環境
- HarmonyOS NEXT、API 12(HarmonyOS 5.0.0)以降、Stage モデル
- 端末種別: スマートフォン、タブレット、2-in-1
- ABI:
arm64-v8a、x86_64(エミュレーター) ohos.permission.INTERNET