Skip to content

React Native SDK ​

SDK 1.2.0

React Native SDK 1.0.0 на основе нативных SDK 1.2.0. Некоторые подробности доступны только на английском: см. английскую версию и журнал изменений.

@captcha-la/react-native добавляет CaptchaLa в приложения React Native на Android и iOS. Текущая версия: 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—Необязательный идентификатор аккаунта.
langstringautoЯзык интерфейса, например "zh-CN", "en", "ja". Не задан = язык устройства. См. Поддерживаемые языки.
theme'auto' | 'light' | 'dark''auto'По умолчанию следует системной теме.
titlestring—Заголовок над проверкой.
timeoutnumber (мс)10000Таймаут HTTP.
retryCount, retryDelaynumberпо умолчанию SDKПовторы сетевых запросов.
enableVoicebooleanпо умолчанию SDKПредлагать аудиозадание.
enableOfflineModebooleanfalseРезервный офлайн-режим, когда серверы недоступны. Тогда результаты содержат isOffline / isClientOnly.
serverTokenstring—Одноразовый токен от вашего бэкенда.
loadingStyle'spinner' | 'ring' | 'dots' | 'none''spinner'Индикатор во время загрузки проверки. См. Индикатор загрузки.
loadingColor'#RRGGBB' / '#RRGGBBAA'белыйЦвет индикатора.
loadingSize'small' | 'medium' | 'large''medium'Размер индикатора.
loadingDelaynumber (мс)300Индикатор показывается, только если проверка загружается дольше этого времени (0–5000).

Чтобы изменить конфигурацию, снова вызовите initialize(), например с новым serverToken.

API ​

МетодОписание
Captchala.initialize(config)Настраивает нативный SDK. Вызывайте до verify(); повторный вызов заменяет конфигурацию.
Captchala.setCallbacks(callbacks)Задаёт callback-и (все необязательны). Заменяет ранее заданные.
Captchala.verify()Показывает проверку. Результаты приходят через callback-и.
Captchala.dismiss()Программно закрывает проверку.

Callback-и ​

CallbackПолучаетКогда
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, чтобы получить ошибку.

Истечение токена ​

Pass token из onSuccess действует ограниченное время, которое определяет сервер. Если форма не использовала его за это время, один раз вызывается onExpired: очистите сохранённый токен и попросите пользователя пройти проверку снова, вместо того чтобы отправлять просроченный токен:

tsx
Captchala.setCallbacks({
  onSuccess: (r) => setPassToken(r.passToken),
  onExpired: () => {
    setPassToken(null);
    setNeedsVerify(true);        // your button calls Captchala.verify() again
  },
});

onExpired вызывается не более одного раза на каждый успех и не вызывается после нового 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 tokens или используйте серверный SDK для PHP / Go.

Устранение неполадок ​

  • The native module for '@captcha-la/react-native' is not linked
    Пересоберите приложение после установки пакета. На iOS сначала выполните pod install в ios/.

  • Сборка iOS не находит CaptchalaSDK
    Выполните pod repo update, а затем pod install в ios/. Deployment target должен быть iOS 13 или выше.

  • Android webview_too_old
    Интерактивной проверке нужен Android System WebView 63+. См. Android SDK.

Требования ​

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

MIT-licensed examples · CaptchaLa is operated independently