--- title: HarmonyOS SDK description: "HarmonyOS NEXT 向け CaptchaLa 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 と同じで、CAPTCHA は現在のページの上にダイアログとして表示され、返される `passToken` をバックエンドで検証します。 ::: info HarmonyOS 4.x 以前は Android アプリが動作する環境です。その場合は [Android SDK](./android) を使用してください。 ::: ## インストール SDK は **ohpm では公開されていません**。ダッシュボードから HAR をダウンロードし、ローカル依存として追加します。 1. ダッシュボードにサインインし、[**SDK ダウンロード**](https://dash.captcha.la/sdk-downloads?platform=harmony) を開きます。同じページで、DevEco Studio で開ける HarmonyOS のデモプロジェクト(ソース)も入手できます。 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 は難読化済みのリリースビルドで、以下に記載する公開 API だけを公開しています。利用側の難読化ルールは HAR に同梱されているため、リリースビルドで keep ルールを追加する必要はありません。 ### 権限 SDK が使う権限は `ohos.permission.INTERNET` の 1 つだけで、実行時権限の要求やダイアログ表示は一切行いません。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. アプリがそれを SDK に渡して CAPTCHA を開きます。 3. `onSuccess` が `passToken` を返し、アプリはそれをバックエンドへ送ります。 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` はアプリではなくバックエンドが、`X-App-Key` + `X-App-Secret` を付けて `/v1/server/challenge/issue` を呼び出して発行します。自社のユーザー ID を `bind_uid` に渡すと、トークンとそこから得られる `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_`)をアプリに返します。`action` は `setAction` に渡した値と一致している必要があります。`setOnServerTokenExpired` を設定しておくと、チャレンジ中にトークンが拒否されたとき SDK が自動で新しいトークンを取得して再試行します。`null` を返すと元のエラーがそのまま通知されます。 本人紐付けのオプション(`bind_uid`、`bind_ip`)はトークン発行時にサーバー側でのみ指定します。アプリから送ることはありません。全パラメーターは [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-expiry)を参照)は任意です。 | | `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`(ネットワーク・設定・システムエラー)に渡されます。 | ```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` | バックエンドから新しい `server_token` を取得する `() => Promise`。 | | `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-expiry} `onSuccess` で受け取る pass token の有効期間には限りがあり、その長さはサーバーが決めます。期限までにページで使われなかった場合、listener の `onExpired(passToken)` が 1 回呼ばれます。保存したトークンを破棄し、期限切れのトークンを送信する代わりにユーザーへ再検証を促してください。新しい検証は `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 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(); ``` ## サーバー側検証 {#server-side-validation} `result.passToken` をバックエンドに転送し、CaptchaLa API で検証します。`X-App-Secret` は決してアプリに含めないでください。 ```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` を発行したユーザーと一致する場合にのみリクエストを受け付けます。トークンは 1 回限りです。レスポンス全体とエラーコードは [API リファレンス](../api-reference) を参照してください。 ## プライバシー {#privacy} SDK は権限不要の端末属性(機種、OS バージョン、画面、ロケール、タイムゾーンなど)を読み取り、検証と不正防止にのみ使用します。既定では端末 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_*` コードが返る** アプリの `setAction` がトークン発行時の `action` と一致しているか、`setOnServerTokenExpired` が新しいトークンを返しているかを確認してください。 - **端末が HarmonyOS 4.x 以前** 非対応です。これらの端末では Android アプリが動作するため、[Android SDK](./android) を使用してください。 ## 動作環境 {#requirements} - HarmonyOS NEXT、API 12(HarmonyOS 5.0.0)以降、Stage モデル - 端末種別: スマートフォン、タブレット、2-in-1 - ABI: `arm64-v8a`、`x86_64`(エミュレーター) - `ohos.permission.INTERNET`