--- title: React Native SDK description: "CaptchaLa React Native SDK 1.0.0 (@captcha-la/react-native) for Android and iOS: install, configuration, callbacks, token expiry, loading indicator and server-side validation." --- # React Native SDK **`@captcha-la/react-native`** adds CaptchaLa to React Native apps on **Android and iOS**. Current version: **1.0.0**. It is a thin bridge over the native SDKs ([Android](./android) `la.captcha:captchala` 1.2.0 and [iOS](./ios) `CaptchalaSDK` 1.2.0): the challenge, its loading indicator and the device checks all run natively. ## Demo on GitHub ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/Captcha-La/react-native-demo) — runnable example app for Android and iOS. ::: ## Install ```bash npm install @captcha-la/react-native cd ios && pod install ``` Autolinking adds the native module on both platforms. Rebuild the app afterwards (`npx react-native run-android` / `run-ios`); a JavaScript reload is not enough. The Android SDK comes from Maven Central and the iOS SDK from CocoaPods, both pulled in automatically. ## Quick start ```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(); ``` Always validate the pass token on your backend before trusting it (see [Server-side validation](#server-side-validation)). ## Configuration `Captchala.initialize(config)`; only `appKey` is required. | Option | Type | Default | Description | | --- | --- | --- | --- | | `appKey` | string | — | Required. Your app key from the [dashboard](https://dash.captcha.la). | | `action` | string | `"default"` | Business action, e.g. `"login"`, `"register"`, `"pay"`. | | `account` | string | — | Optional account identifier. | | `lang` | string | auto | UI language, e.g. `"zh-CN"`, `"en"`, `"ja"`. Unset = the device language. See [Supported languages](../supported-languages). | | `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Follows the system by default. | | `title` | string | — | Title above the challenge. | | `timeout` | number (ms) | `10000` | HTTP timeout. | | `retryCount`, `retryDelay` | number | SDK default | Network retries. | | `enableVoice` | boolean | SDK default | Offer the audio challenge. | | `enableOfflineMode` | boolean | `false` | Offline fallback when the servers are unreachable. Results then carry `isOffline` / `isClientOnly`. | | `serverToken` | string | — | One-time token from your backend. | | `loadingStyle` | `'spinner' \| 'ring' \| 'dots' \| 'none'` | `'spinner'` | Indicator while the challenge loads. See [Loading indicator](#loading-indicator). | | `loadingColor` | `'#RRGGBB'` / `'#RRGGBBAA'` | white | Indicator colour. | | `loadingSize` | `'small' \| 'medium' \| 'large'` | `'medium'` | Indicator size. | | `loadingDelay` | number (ms) | `300` | Shown only if the challenge takes longer than this (`0`–`5000`). | Call `initialize()` again to change the config, for example with a new `serverToken`. ## API | Method | Description | | --- | --- | | `Captchala.initialize(config)` | Configure the native SDK. Call it before `verify()`; calling it again replaces the config. | | `Captchala.setCallbacks(callbacks)` | Set the callbacks (all optional). Replaces earlier ones. | | `Captchala.verify()` | Show the challenge. Results arrive through the callbacks. | | `Captchala.dismiss()` | Close the challenge programmatically. | ### Callbacks | Callback | Receives | When | | --- | --- | --- | | `onReady` | — | The challenge is on screen. | | `onSuccess` | `{ passToken, challengeId, isOffline, isClientOnly }` | Verified. Send `passToken` to your backend. | | `onFail` | `{ code, message }` | The user did not pass; they can try again. | | `onError` | `{ code, message }` | Network, configuration or system error. Branch on `code`; `message` is English diagnostic text. | | `onClose` | — | The user closed the challenge. | | `onExpired` | `passToken` | The pass token expired before it was used. See [Token expiry](#token-expiry). | | `onServerTokenExpired` | — | The server token was rejected. Return a new one from your backend (a `Promise`) and the SDK continues; return `null` to report the error. | ## Token expiry {#token-expiry} The pass token from `onSuccess` is valid for a limited time, decided by the server. If your form has not used it by then, `onExpired` is called once, so you can clear the stored token and ask the user to verify again instead of submitting an expired one: ```tsx Captchala.setCallbacks({ onSuccess: (r) => setPassToken(r.passToken), onExpired: () => { setPassToken(null); setNeedsVerify(true); // your button calls Captchala.verify() again }, }); ``` `onExpired` is called at most once per success and not after a new `verify()` or `initialize()`. ## Loading indicator {#loading-indicator} While the challenge loads, the native SDK shows a small indicator on the dim. It appears only when loading takes longer than `loadingDelay` and disappears when the challenge is shown. `'spinner'` (default) is the classic spokes, `'ring'` a turning arc. With `'none'` nothing is shown: show your own indicator from `verify()` until `onReady`. ```tsx await Captchala.initialize({ appKey: 'YOUR_APP_KEY', loadingStyle: 'dots', loadingColor: '#3B82F6', loadingSize: 'small', loadingDelay: 500, }); ``` ## Server-side validation Send `passToken` to your backend and validate it there. Never put `X-App-Secret` in the app. ```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": "" } ``` To issue the optional one-time `serverToken`, your backend calls `POST /v1/server/challenge/issue`. See the [API Reference](../api-reference) and [server tokens](../api-reference#server-token), or use the [PHP](./server-php) / [Go](./server-go) server SDK. ## Troubleshooting - **`The native module for '@captcha-la/react-native' is not linked`** Rebuild the app after installing the package. On iOS run `pod install` in `ios/` first. - **iOS build cannot find `CaptchalaSDK`** Run `pod repo update` and then `pod install` in `ios/`. The deployment target must be iOS 13 or higher. - **Android `webview_too_old`** The interactive challenge needs Android System WebView 63+. See the [Android SDK](./android#webview-too-old). ## Requirements - React Native 0.73+ (New and Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+