--- title: React Native SDK description: "CaptchaLa React Native SDK 1.0.0(@captcha-la/react-native)Android / iOS 向け:インストール、設定、コールバック、トークンの有効期限、読み込みインジケーター、サーバー側検証。" --- # React Native SDK **`@captcha-la/react-native`** は、**Android と iOS** の React Native アプリに CaptchaLa を組み込むためのパッケージです。現在のバージョン: **1.0.0**。ネイティブ SDK([Android](./android) `la.captcha:captchala` 1.2.0 と [iOS](./ios) `CaptchalaSDK` 1.2.0)の上に載る薄いブリッジで、チャレンジ、読み込みインジケーター、デバイスチェックはすべてネイティブ側で動作します。 ## GitHub のデモ ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/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` のみです。 | オプション | 型 | デフォルト | 説明 | | --- | --- | --- | --- | | `appKey` | string | — | 必須。[ダッシュボード](https://dash.captcha.la)で発行した App Key。 | | `action` | string | `"default"` | 業務アクション。例: `"login"`、`"register"`、`"pay"`。 | | `account` | string | — | 任意のアカウント識別子。 | | `lang` | string | 自動 | UI の言語。例: `"zh-CN"`、`"en"`、`"ja"`。未設定ならデバイスの言語。[対応言語](../supported-languages)を参照。 | | `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'` | チャレンジ読み込み中のインジケーター。[読み込みインジケーター](#loading-indicator)を参照。 | | `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 が使われる前に期限切れになった。[トークンの有効期限](#token-expiry)を参照。 | | `onServerTokenExpired` | — | server token が拒否された。バックエンドから新しいトークンを返す(`Promise`)と SDK は処理を続行します。`null` を返すとエラーとして報告されます。 | ## トークンの有効期限 {#token-expiry} `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()` の後には呼ばれません。 ## 読み込みインジケーター {#loading-indicator} チャレンジの読み込み中、ネイティブ 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": "" } ``` 任意のワンタイム `serverToken` を発行するには、バックエンドから `POST /v1/server/challenge/issue` を呼び出します。[API リファレンス](../api-reference)と [server token](../api-reference#server-token) を参照するか、[PHP](./server-php) / [Go](./server-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](./android) を参照してください。 ## 動作環境 - React Native 0.73+(New Architecture / Old Architecture の両方) - Android 5.0+(`minSdk 21`) - iOS 13+