Skip to content

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 で動作するサンプルアプリ。

インストール ​

bash
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 から自動的に取り込まれます。

クイックスタート ​

tsx
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 のみです。

オプション型デフォルト説明
appKeystring—必須。ダッシュボードで発行した App Key。
actionstring"default"業務アクション。例: "login"、"register"、"pay"。
accountstring—任意のアカウント識別子。
langstring自動UI の言語。例: "zh-CN"、"en"、"ja"。未設定ならデバイスの言語。対応言語を参照。
theme'auto' | 'light' | 'dark''auto'デフォルトではシステムに従います。
titlestring—チャレンジの上に表示するタイトル。
timeoutnumber(ミリ秒)10000HTTP タイムアウト。
retryCount、retryDelaynumberSDK のデフォルトネットワークのリトライ。
enableVoicebooleanSDK のデフォルト音声チャレンジを提供します。
enableOfflineModebooleanfalseサーバーに到達できないときのオフラインフォールバック。その場合、結果に isOffline / isClientOnly が付きます。
serverTokenstring—バックエンドが発行したワンタイムトークン。
loadingStyle'spinner' | 'ring' | 'dots' | 'none''spinner'チャレンジ読み込み中のインジケーター。読み込みインジケーターを参照。
loadingColor'#RRGGBB' / '#RRGGBBAA'白インジケーターの色。
loadingSize'small' | 'medium' | 'large''medium'インジケーターのサイズ。
loadingDelaynumber(ミリ秒)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—ユーザーがチャレンジを閉じた。
onExpiredpassTokenpass token が使われる前に期限切れになった。トークンの有効期限を参照。
onServerTokenExpired—server token が拒否された。バックエンドから新しいトークンを返す(Promise<string>)と SDK は処理を続行します。null を返すとエラーとして報告されます。

トークンの有効期限 ​

onSuccess で受け取った pass token の有効期間は限られており、サーバーが決定します。それまでにフォームで使われなかった場合は onExpired が一度だけ呼ばれます。期限切れのトークンを送信する代わりに、保存したトークンを破棄してユーザーに再検証を促してください。

tsx
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 までの間は独自のインジケーターを表示してください。

tsx
await Captchala.initialize({
  appKey: 'YOUR_APP_KEY',
  loadingStyle: 'dots',
  loadingColor: '#3B82F6',
  loadingSize: 'small',
  loadingDelay: 500,
});

サーバー側検証 ​

passToken をバックエンドに送り、そこで検証してください。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": "<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+

MIT-licensed examples · CaptchaLa is operated independently