Skip to content

SDK React Native ​

SDK 1.2.0

React Native 1.0.0, construído sobre o SDK 1.2.0. Alguns detalhes estão disponíveis apenas em inglês: veja a página em inglês e o changelog.

@captcha-la/react-native adiciona a CaptchaLa a apps React Native no Android e iOS. Versão atual: 1.0.0. É uma ponte fina sobre os SDKs nativos (Android la.captcha:captchala 1.2.0 e iOS CaptchalaSDK 1.2.0): o desafio, o indicador de carregamento e as verificações do dispositivo rodam todos no código nativo.

Demonstração no GitHub ​

📦

Captcha-La/react-native-demo — app de exemplo executável para Android e iOS.

Instalação ​

bash
npm install @captcha-la/react-native
cd ios && pod install

O autolinking adiciona o módulo nativo nas duas plataformas. Recompile o app depois (npx react-native run-android / run-ios); recarregar o JavaScript não basta. O SDK Android vem do Maven Central e o SDK iOS do CocoaPods, ambos incluídos automaticamente.

Início 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();

Sempre valide o pass token no seu backend antes de confiar nele (veja Validação no servidor).

Configuração ​

Captchala.initialize(config); apenas appKey é obrigatório.

OpçãoTipoPadrãoDescrição
appKeystring—Obrigatório. A App Key do painel.
actionstring"default"Ação de negócio, por exemplo "login", "register", "pay".
accountstring—Identificador de conta opcional.
langstringautoIdioma da interface, por exemplo "zh-CN", "en", "ja". Sem valor = o idioma do dispositivo. Veja Idiomas suportados.
theme'auto' | 'light' | 'dark''auto'Por padrão segue o sistema.
titlestring—Título acima do desafio.
timeoutnumber (ms)10000Tempo limite HTTP.
retryCount, retryDelaynumberpadrão do SDKNovas tentativas de rede.
enableVoicebooleanpadrão do SDKOferece o desafio em áudio.
enableOfflineModebooleanfalseAlternativa offline quando os servidores estão inacessíveis. Os resultados então trazem isOffline / isClientOnly.
serverTokenstring—Token de uso único emitido pelo seu backend.
loadingStyle'spinner' | 'ring' | 'dots' | 'none''spinner'Indicador enquanto o desafio carrega. Veja Indicador de carregamento.
loadingColor'#RRGGBB' / '#RRGGBBAA'brancoCor do indicador.
loadingSize'small' | 'medium' | 'large''medium'Tamanho do indicador.
loadingDelaynumber (ms)300Exibido apenas se o desafio demorar mais que isso (0–5000).

Chame initialize() de novo para mudar a configuração, por exemplo com um novo serverToken.

API ​

MétodoDescrição
Captchala.initialize(config)Configura o SDK nativo. Chame antes de verify(); chamar de novo substitui a configuração.
Captchala.setCallbacks(callbacks)Define os callbacks (todos opcionais). Substitui os anteriores.
Captchala.verify()Exibe o desafio. Os resultados chegam pelos callbacks.
Captchala.dismiss()Fecha o desafio por código.

Callbacks ​

CallbackRecebeQuando
onReady—O desafio está na tela.
onSuccess{ passToken, challengeId, isOffline, isClientOnly }Verificado. Envie passToken ao seu backend.
onFail{ code, message }O usuário não passou; pode tentar de novo.
onError{ code, message }Erro de rede, configuração ou sistema. Use code para decidir; message é um texto de diagnóstico em inglês.
onClose—O usuário fechou o desafio.
onExpiredpassTokenO pass token expirou antes de ser usado. Veja Expiração do token.
onServerTokenExpired—O server token foi rejeitado. Retorne um novo token do seu backend (uma Promise<string>) e o SDK continua; retorne null para reportar o erro.

Expiração do token ​

O pass token recebido em onSuccess tem validade limitada, definida pelo servidor. Se o seu formulário não o usar até lá, onExpired é chamado uma única vez, para que você descarte o token guardado e peça ao usuário que verifique de novo, em vez de enviar um token expirado:

tsx
Captchala.setCallbacks({
  onSuccess: (r) => setPassToken(r.passToken),
  onExpired: () => {
    setPassToken(null);
    setNeedsVerify(true);        // your button calls Captchala.verify() again
  },
});

onExpired é chamado no máximo uma vez por sucesso e não depois de um novo verify() ou initialize().

Indicador de carregamento ​

Enquanto o desafio carrega, o SDK nativo mostra um pequeno indicador sobre o fundo escurecido. Ele só aparece quando o carregamento demora mais que loadingDelay e some quando o desafio é exibido. 'spinner' (padrão) são os raios clássicos, 'ring' um arco girando. Com 'none' nada é exibido: mostre seu próprio indicador de verify() até onReady.

tsx
await Captchala.initialize({
  appKey: 'YOUR_APP_KEY',
  loadingStyle: 'dots',
  loadingColor: '#3B82F6',
  loadingSize: 'small',
  loadingDelay: 500,
});

Validação no servidor ​

Envie passToken ao seu backend e valide-o lá. Nunca coloque X-App-Secret no 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 o serverToken opcional de uso único, o seu backend chama POST /v1/server/challenge/issue. Veja a Referência da API e server tokens, ou use o SDK de servidor PHP / Go.

Solução de problemas ​

  • The native module for '@captcha-la/react-native' is not linked
    Recompile o app depois de instalar o pacote. No iOS, execute antes pod install em ios/.

  • O build do iOS não encontra CaptchalaSDK
    Execute pod repo update e depois pod install em ios/. O deployment target precisa ser iOS 13 ou superior.

  • Android webview_too_old
    O desafio interativo precisa do Android System WebView 63+. Veja o SDK Android em inglês.

Requisitos ​

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

MIT-licensed examples · CaptchaLa is operated independently