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 と同じで、CAPTCHA は現在のページの上にダイアログとして表示され、返される passToken をバックエンドで検証します。

INFO

HarmonyOS 4.x 以前は Android アプリが動作する環境です。その場合は Android SDK を使用してください。

インストール ​

SDK は ohpm では公開されていません。ダッシュボードから HAR をダウンロードし、ローカル依存として追加します。

  1. ダッシュボードにサインインし、SDK ダウンロード を開きます。同じページで、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
  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 は難読化済みのリリースビルドで、以下に記載する公開 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 を参照)。
  2. アプリがそれを SDK に渡して CAPTCHA を開きます。
  3. onSuccess が passToken を返し、アプリはそれをバックエンドへ送ります。
  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 はアプリではなくバックエンドが、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 リファレンス を参照するか、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()シングルトンを解放します。
CaptchalaResultpassToken、challengeId、ttl、isOffline、isClientOnly。passToken をバックエンドへ送ります。ttl は 1.2.0 で非推奨になりました。トークンの有効期間はサーバーが決め、変更されることがあるため、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バックエンドから新しい 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() で開始します。

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 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();

サーバー側検証 ​

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": "<result.passToken>", "expected_action": "login" }

data.valid が true で、かつ data.uid が server_token を発行したユーザーと一致する場合にのみリクエストを受け付けます。トークンは 1 回限りです。レスポンス全体とエラーコードは API リファレンス を参照してください。

プライバシー ​

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 のプライバシーラベルで「不正防止に使用する端末識別子」を申告してください。

トラブルシューティング ​

  • 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

MIT-licensed examples · CaptchaLa is operated independently