--- title: React Native SDK description: "React Native SDK CaptchaLa 1.0.0 (@captcha-la/react-native) для Android и iOS: установка, конфигурация, callback-и, истечение токена, индикатор загрузки и серверная проверка." --- # React Native SDK ::: info SDK 1.2.0 React Native SDK 1.0.0 на основе нативных SDK 1.2.0. Некоторые подробности доступны только на английском: см. [английскую версию](/sdk/react-native) и [журнал изменений](/changelog#sdk-1-2-0). ::: **`@captcha-la/react-native`** добавляет CaptchaLa в приложения React Native на **Android и iOS**. Текущая версия: **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 на своём бэкенде, прежде чем доверять ему (см. [Серверная проверка](#server-side-validation)). ## Конфигурация `Captchala.initialize(config)`; обязателен только `appKey`. | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `appKey` | string | — | Обязательно. Ваш App Key из [панели управления](https://dash.captcha.la). | | `action` | string | `"default"` | Бизнес-действие, например `"login"`, `"register"`, `"pay"`. | | `account` | string | — | Необязательный идентификатор аккаунта. | | `lang` | string | auto | Язык интерфейса, например `"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`). | Чтобы изменить конфигурацию, снова вызовите `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 истёк до использования. См. [Истечение токена](#token-expiry). | | `onServerTokenExpired` | — | Server token отклонён. Верните новый токен от своего бэкенда (`Promise`), и SDK продолжит работу; верните `null`, чтобы получить ошибку. | ## Истечение токена {#token-expiry} 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()`. ## Индикатор загрузки {#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, }); ``` ## Серверная проверка {#server-side-validation} Отправьте `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 tokens](../api-reference#server-token) или используйте серверный SDK для [PHP](./server-php) / [Go](./server-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](/sdk/android#webview-too-old). ## Требования - React Native 0.73+ (New и Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+