React Native SDK
@captcha-la/react-native は、Android と iOS の React Native アプリに CaptchaLa を組み込むためのパッケージです。現在のバージョン: 1.0.0。ネイティブ SDK(Android la.captcha:captchala 1.2.0 と iOS CaptchalaSDK 1.2.0)の上に載る薄いブリッジで、チャレンジ、読み込みインジケーター、デバイスチェックはすべてネイティブ側で動作します。
GitHub のデモ
📦
Captcha-La/react-native-demo — Android / iOS で動作するサンプルアプリ。
インストール
npm install @captcha-la/react-native
cd ios && pod install自動リンク(autolinking)により、両プラットフォームにネイティブモジュールが追加されます。インストール後はアプリを再ビルドしてください(npx react-native run-android / run-ios)。JavaScript のリロードだけでは反映されません。Android SDK は Maven Central から、iOS SDK は CocoaPods から自動的に取り込まれます。
クイックスタート
import Captchala from '@captcha-la/react-native';
Captchala.setCallbacks({
onReady: () => {}, // the challenge is on screen
onSuccess: (r) => submit(r.passToken), // send the pass token to your backend
onFail: (e) => {}, // the user did not pass (can retry)
onError: (e) => {}, // network, configuration or system error
onClose: () => {}, // closed by the user
onExpired: () => {}, // the pass token expired: ask to verify again
onServerTokenExpired: async () => fetchServerTokenFromYourBackend(),
});
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
action: 'login',
serverToken, // one-time token from your backend, if your app requires one
});
await Captchala.verify();pass token を信頼する前に、必ずバックエンドで検証してください(サーバー側検証を参照)。
設定
Captchala.initialize(config)。必須は appKey のみです。
| オプション | 型 | デフォルト | 説明 |
|---|---|---|---|
appKey | string | — | 必須。ダッシュボードで発行した App Key。 |
action | string | "default" | 業務アクション。例: "login"、"register"、"pay"。 |
account | string | — | 任意のアカウント識別子。 |
lang | string | 自動 | UI の言語。例: "zh-CN"、"en"、"ja"。未設定ならデバイスの言語。対応言語を参照。 |
theme | 'auto' | 'light' | 'dark' | 'auto' | デフォルトではシステムに従います。 |
title | string | — | チャレンジの上に表示するタイトル。 |
timeout | number(ミリ秒) | 10000 | HTTP タイムアウト。 |
retryCount、retryDelay | number | SDK のデフォルト | ネットワークのリトライ。 |
enableVoice | boolean | SDK のデフォルト | 音声チャレンジを提供します。 |
enableOfflineMode | boolean | false | サーバーに到達できないときのオフラインフォールバック。その場合、結果に isOffline / isClientOnly が付きます。 |
serverToken | string | — | バックエンドが発行したワンタイムトークン。 |
loadingStyle | 'spinner' | 'ring' | 'dots' | 'none' | 'spinner' | チャレンジ読み込み中のインジケーター。読み込みインジケーターを参照。 |
loadingColor | '#RRGGBB' / '#RRGGBBAA' | 白 | インジケーターの色。 |
loadingSize | 'small' | 'medium' | 'large' | 'medium' | インジケーターのサイズ。 |
loadingDelay | number(ミリ秒) | 300 | チャレンジの読み込みがこの時間を超えた場合にのみ表示します(0–5000)。 |
設定を変更するには、新しい serverToken などを渡して initialize() を再度呼び出します。
API
| メソッド | 説明 |
|---|---|
Captchala.initialize(config) | ネイティブ SDK を設定します。verify() の前に呼び出してください。再度呼ぶと設定が置き換わります。 |
Captchala.setCallbacks(callbacks) | コールバックを設定します(すべて任意)。以前の設定は置き換わります。 |
Captchala.verify() | チャレンジを表示します。結果はコールバックで届きます。 |
Captchala.dismiss() | プログラムからチャレンジを閉じます。 |
コールバック
| コールバック | 引数 | 呼ばれるタイミング |
|---|---|---|
onReady | — | チャレンジが画面に表示された。 |
onSuccess | { passToken, challengeId, isOffline, isClientOnly } | 検証に成功した。passToken をバックエンドに送ってください。 |
onFail | { code, message } | ユーザーが通過できなかった(再試行可能)。 |
onError | { code, message } | ネットワーク、設定、またはシステムのエラー。code で分岐してください。message は英語の診断用テキストです。 |
onClose | — | ユーザーがチャレンジを閉じた。 |
onExpired | passToken | pass token が使われる前に期限切れになった。トークンの有効期限を参照。 |
onServerTokenExpired | — | server token が拒否された。バックエンドから新しいトークンを返す(Promise<string>)と SDK は処理を続行します。null を返すとエラーとして報告されます。 |
トークンの有効期限
onSuccess で受け取った pass token の有効期間は限られており、サーバーが決定します。それまでにフォームで使われなかった場合は onExpired が一度だけ呼ばれます。期限切れのトークンを送信する代わりに、保存したトークンを破棄してユーザーに再検証を促してください。
Captchala.setCallbacks({
onSuccess: (r) => setPassToken(r.passToken),
onExpired: () => {
setPassToken(null);
setNeedsVerify(true); // your button calls Captchala.verify() again
},
});onExpired は 1 回の成功につき最大 1 回呼ばれ、新しい verify() や initialize() の後には呼ばれません。
読み込みインジケーター
チャレンジの読み込み中、ネイティブ SDK は背景の暗幕上に小さなインジケーターを表示します。読み込みが loadingDelay より長くかかった場合にのみ表示され、チャレンジが表示されると消えます。'spinner'(デフォルト)は従来のスポーク型、'ring' は回転する円弧です。'none' にすると何も表示しないので、verify() から onReady までの間は独自のインジケーターを表示してください。
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
loadingStyle: 'dots',
loadingColor: '#3B82F6',
loadingSize: 'small',
loadingDelay: 500,
});サーバー側検証
passToken をバックエンドに送り、そこで検証してください。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": "<passToken>" }任意のワンタイム serverToken を発行するには、バックエンドから POST /v1/server/challenge/issue を呼び出します。API リファレンスと server token を参照するか、PHP / Go のサーバー SDK を使ってください。
トラブルシューティング
The native module for '@captcha-la/react-native' is not linked
パッケージをインストールした後、アプリを再ビルドしてください。iOS では先にios/でpod installを実行します。iOS のビルドで
CaptchalaSDKが見つからないios/でpod repo updateを実行してからpod installを実行してください。デプロイメントターゲットは iOS 13 以上が必要です。Android の
webview_too_old
インタラクティブなチャレンジには Android System WebView 63 以上が必要です。Android SDK を参照してください。
動作環境
- React Native 0.73+(New Architecture / Old Architecture の両方)
- Android 5.0+(
minSdk 21) - iOS 13+