Skip to content

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 la.captcha:captchala 1.2.0 and iOS CaptchalaSDK 1.2.0): the challenge, its loading indicator and the device checks all run natively.

Demo on GitHub ​

📦

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).

Configuration ​

Captchala.initialize(config); only appKey is required.

OptionTypeDefaultDescription
appKeystring—Required. Your app key from the dashboard.
actionstring"default"Business action, e.g. "login", "register", "pay".
accountstring—Optional account identifier.
langstringautoUI language, e.g. "zh-CN", "en", "ja". Unset = the device language. See Supported languages.
theme'auto' | 'light' | 'dark''auto'Follows the system by default.
titlestring—Title above the challenge.
timeoutnumber (ms)10000HTTP timeout.
retryCount, retryDelaynumberSDK defaultNetwork retries.
enableVoicebooleanSDK defaultOffer the audio challenge.
enableOfflineModebooleanfalseOffline fallback when the servers are unreachable. Results then carry isOffline / isClientOnly.
serverTokenstring—One-time token from your backend.
loadingStyle'spinner' | 'ring' | 'dots' | 'none''spinner'Indicator while the challenge loads. See Loading indicator.
loadingColor'#RRGGBB' / '#RRGGBBAA'whiteIndicator colour.
loadingSize'small' | 'medium' | 'large''medium'Indicator size.
loadingDelaynumber (ms)300Shown only if the challenge takes longer than this (0–5000).

Call initialize() again to change the config, for example with a new serverToken.

API ​

MethodDescription
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 ​

CallbackReceivesWhen
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.
onExpiredpassTokenThe pass token expired before it was used. See Token expiry.
onServerTokenExpired—The server token was rejected. Return a new one from your backend (a Promise<string>) and the SDK continues; return null to report the error.

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 ​

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": "<passToken>" }

To issue the optional one-time serverToken, your backend calls POST /v1/server/challenge/issue. See the API Reference and server tokens, or use the PHP / 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.

Requirements ​

  • React Native 0.73+ (New and Old Architecture)
  • Android 5.0+ (minSdk 21)
  • iOS 13+

MIT-licensed examples · CaptchaLa is operated independently