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 la.captcha:captchala 1.2.0 e 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
📦
Captcha-La/react-native-demo — app de ejemplo ejecutable para Android e iOS.
Instalación
npm install @captcha-la/react-native
cd ios && pod installEl 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
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).
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. |
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. |
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. |
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. |
onServerTokenExpired | — | El server token fue rechazado. Devuelve uno nuevo de tu backend (una Promise<string>) y el SDK continúa; devuelve null para notificar el error. |
Caducidad del token
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:
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
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.
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
loadingStyle: 'dots',
loadingColor: '#3B82F6',
loadingSize: 'small',
loadingDelay: 500,
});Validación en el servidor
Envía passToken a tu backend y valídalo allí. Nunca incluyas X-App-Secret en la app.
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>" }Para emitir el serverToken opcional de un solo uso, tu backend llama a POST /v1/server/challenge/issue. Consulta la Referencia de la API y los server tokens, o usa el SDK de servidor de PHP / 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 antespod installenios/.La compilación de iOS no encuentra
CaptchalaSDK
Ejecutapod repo updatey despuéspod installenios/. 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.
Requisitos
- React Native 0.73+ (New Architecture y Old Architecture)
- Android 5.0+ (
minSdk 21) - iOS 13+