--- title: SDK React Native description: "SDK de React Native de CaptchaLa 1.0.0 (@captcha-la/react-native) para Android e iOS: instalación, configuración, callbacks, caducidad del token, indicador de carga y validación en el servidor." --- # SDK React Native **`@captcha-la/react-native`** añade CaptchaLa a apps de React Native en **Android e iOS**. Versión actual: **1.0.0**. Es un puente ligero sobre los SDK nativos ([Android](./android) `la.captcha:captchala` 1.2.0 e [iOS](./ios) `CaptchalaSDK` 1.2.0): el desafío, su indicador de carga y las comprobaciones del dispositivo se ejecutan de forma nativa. ## Demo en GitHub ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/Captcha-La/react-native-demo) — app de ejemplo ejecutable para Android e iOS. ::: ## Instalación ```bash npm install @captcha-la/react-native cd ios && pod install ``` El autolinking añade el módulo nativo en ambas plataformas. Después vuelve a compilar la app (`npx react-native run-android` / `run-ios`); recargar el JavaScript no basta. El SDK de Android viene de Maven Central y el de iOS de CocoaPods; ambos se incorporan automáticamente. ## Inicio rápido ```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(); ``` Valida siempre el pass token en tu backend antes de confiar en él (consulta [Validación en el servidor](#server-side-validation)). ## Configuración `Captchala.initialize(config)`; solo `appKey` es obligatorio. | Opción | Tipo | Valor por defecto | Descripción | | --- | --- | --- | --- | | `appKey` | string | — | Obligatorio. Tu app key del [panel](https://dash.captcha.la). | | `action` | string | `"default"` | Acción de negocio, p. ej. `"login"`, `"register"`, `"pay"`. | | `account` | string | — | Identificador de cuenta opcional. | | `lang` | string | automático | Idioma de la interfaz, p. ej. `"zh-CN"`, `"en"`, `"ja"`. Sin definir = idioma del dispositivo. Consulta [Idiomas compatibles](../supported-languages). | | `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Sigue al sistema por defecto. | | `title` | string | — | Título sobre el desafío. | | `timeout` | number (ms) | `10000` | Tiempo de espera HTTP. | | `retryCount`, `retryDelay` | number | valor del SDK | Reintentos de red. | | `enableVoice` | boolean | valor del SDK | Ofrece el desafío de audio. | | `enableOfflineMode` | boolean | `false` | Alternativa sin conexión cuando los servidores no son accesibles. Los resultados incluyen entonces `isOffline` / `isClientOnly`. | | `serverToken` | string | — | Token de un solo uso de tu backend. | | `loadingStyle` | `'spinner' \| 'ring' \| 'dots' \| 'none'` | `'spinner'` | Indicador mientras se carga el desafío. Consulta [Indicador de carga](#loading-indicator). | | `loadingColor` | `'#RRGGBB'` / `'#RRGGBBAA'` | blanco | Color del indicador. | | `loadingSize` | `'small' \| 'medium' \| 'large'` | `'medium'` | Tamaño del indicador. | | `loadingDelay` | number (ms) | `300` | Solo se muestra si el desafío tarda más que esto (`0`–`5000`). | Llama de nuevo a `initialize()` para cambiar la configuración, por ejemplo con un `serverToken` nuevo. ## API | Método | Descripción | | --- | --- | | `Captchala.initialize(config)` | Configura el SDK nativo. Llámalo antes de `verify()`; llamarlo de nuevo reemplaza la configuración. | | `Captchala.setCallbacks(callbacks)` | Define los callbacks (todos opcionales). Reemplaza los anteriores. | | `Captchala.verify()` | Muestra el desafío. Los resultados llegan a través de los callbacks. | | `Captchala.dismiss()` | Cierra el desafío desde el código. | ### Callbacks | Callback | Recibe | Cuándo | | --- | --- | --- | | `onReady` | — | El desafío está en pantalla. | | `onSuccess` | `{ passToken, challengeId, isOffline, isClientOnly }` | Verificado. Envía `passToken` a tu backend. | | `onFail` | `{ code, message }` | El usuario no superó el desafío; puede volver a intentarlo. | | `onError` | `{ code, message }` | Error de red, configuración o sistema. Decide según `code`; `message` es texto de diagnóstico en inglés. | | `onClose` | — | El usuario cerró el desafío. | | `onExpired` | `passToken` | El pass token caducó antes de usarse. Consulta [Caducidad del token](#token-expiry). | | `onServerTokenExpired` | — | El server token fue rechazado. Devuelve uno nuevo de tu backend (una `Promise`) y el SDK continúa; devuelve `null` para notificar el error. | ## Caducidad del token {#token-expiry} El pass token de `onSuccess` es válido durante un tiempo limitado que decide el servidor. Si tu formulario no lo ha usado para entonces, se llama una vez a `onExpired`, para que puedas borrar el token guardado y pedir al usuario que vuelva a verificar en lugar de enviar un token caducado: ```tsx Captchala.setCallbacks({ onSuccess: (r) => setPassToken(r.passToken), onExpired: () => { setPassToken(null); setNeedsVerify(true); // your button calls Captchala.verify() again }, }); ``` `onExpired` se llama como máximo una vez por cada éxito y no después de un nuevo `verify()` o `initialize()`. ## Indicador de carga {#loading-indicator} Mientras se carga el desafío, el SDK nativo muestra un pequeño indicador sobre la capa de oscurecimiento. Solo aparece si la carga tarda más que `loadingDelay` y desaparece cuando se muestra el desafío. `'spinner'` (por defecto) son los radios clásicos; `'ring'`, un arco que gira. Con `'none'` no se muestra nada: muestra tu propio indicador desde `verify()` hasta `onReady`. ```tsx await Captchala.initialize({ appKey: 'YOUR_APP_KEY', loadingStyle: 'dots', loadingColor: '#3B82F6', loadingSize: 'small', loadingDelay: 500, }); ``` ## Validación en el servidor {#server-side-validation} Envía `passToken` a tu backend y valídalo allí. Nunca incluyas `X-App-Secret` en la 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": "" } ``` Para emitir el `serverToken` opcional de un solo uso, tu backend llama a `POST /v1/server/challenge/issue`. Consulta la [Referencia de la API](../api-reference) y los [server tokens](../api-reference#server-token), o usa el SDK de servidor de [PHP](./server-php) / [Go](./server-go). ## Solución de problemas - **`The native module for '@captcha-la/react-native' is not linked`** Vuelve a compilar la app después de instalar el paquete. En iOS ejecuta antes `pod install` en `ios/`. - **La compilación de iOS no encuentra `CaptchalaSDK`** Ejecuta `pod repo update` y después `pod install` en `ios/`. El deployment target debe ser iOS 13 o superior. - **Android `webview_too_old`** El desafío interactivo necesita Android System WebView 63+. Consulta el [SDK de Android](/sdk/android#webview-too-old). ## Requisitos - React Native 0.73+ (New Architecture y Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+