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.
Установка
npm install @captcha-la/react-native
cd ios && pod installAutolinking подключает нативный модуль на обеих платформах. После этого пересоберите приложение (npx react-native run-android / run-ios); перезагрузки JavaScript недостаточно. Android SDK загружается из Maven Central, а iOS SDK — из CocoaPods; оба подтягиваются автоматически.
Быстрый старт
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 | — | Обязательно. Ваш App Key из панели управления. |
action | string | "default" | Бизнес-действие, например "login", "register", "pay". |
account | string | — | Необязательный идентификатор аккаунта. |
lang | string | auto | Язык интерфейса, например "zh-CN", "en", "ja". Не задан = язык устройства. См. Поддерживаемые языки. |
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' | Индикатор во время загрузки проверки. См. Индикатор загрузки. |
loadingColor | '#RRGGBB' / '#RRGGBBAA' | белый | Цвет индикатора. |
loadingSize | 'small' | 'medium' | 'large' | 'medium' | Размер индикатора. |
loadingDelay | number (мс) | 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 | — | Пользователь закрыл проверку. |
onExpired | passToken | Pass token истёк до использования. См. Истечение токена. |
onServerTokenExpired | — | Server token отклонён. Верните новый токен от своего бэкенда (Promise<string>), и SDK продолжит работу; верните null, чтобы получить ошибку. |
Истечение токена
Pass token из onSuccess действует ограниченное время, которое определяет сервер. Если форма не использовала его за это время, один раз вызывается onExpired: очистите сохранённый токен и попросите пользователя пройти проверку снова, вместо того чтобы отправлять просроченный токен:
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.
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
loadingStyle: 'dots',
loadingColor: '#3B82F6',
loadingSize: 'small',
loadingDelay: 500,
});Серверная проверка
Отправьте passToken на свой бэкенд и проверьте его там. Никогда не помещайте X-App-Secret в приложение.
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+