Skip to content

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 ​

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).

Configuración ​

Captchala.initialize(config); solo appKey es obligatorio.

OpciónTipoValor por defectoDescripción
appKeystring—Obligatorio. Tu app key del panel.
actionstring"default"Acción de negocio, p. ej. "login", "register", "pay".
accountstring—Identificador de cuenta opcional.
langstringautomáticoIdioma 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.
titlestring—Título sobre el desafío.
timeoutnumber (ms)10000Tiempo de espera HTTP.
retryCount, retryDelaynumbervalor del SDKReintentos de red.
enableVoicebooleanvalor del SDKOfrece el desafío de audio.
enableOfflineModebooleanfalseAlternativa sin conexión cuando los servidores no son accesibles. Los resultados incluyen entonces isOffline / isClientOnly.
serverTokenstring—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'blancoColor del indicador.
loadingSize'small' | 'medium' | 'large''medium'Tamaño del indicador.
loadingDelaynumber (ms)300Solo 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étodoDescripció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 ​

CallbackRecibeCuá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.
onExpiredpassTokenEl 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:

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 ​

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 ​

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": "<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 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.

Requisitos ​

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

MIT-licensed examples · CaptchaLa is operated independently