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
npm install @captcha-la/react-native
cd ios && pod installO 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
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ção | Tipo | Padrão | Descrição |
|---|---|---|---|
appKey | string | — | Obrigatório. A App Key do painel. |
action | string | "default" | Ação de negócio, por exemplo "login", "register", "pay". |
account | string | — | Identificador de conta opcional. |
lang | string | auto | Idioma 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. |
title | string | — | Título acima do desafio. |
timeout | number (ms) | 10000 | Tempo limite HTTP. |
retryCount, retryDelay | number | padrão do SDK | Novas tentativas de rede. |
enableVoice | boolean | padrão do SDK | Oferece o desafio em áudio. |
enableOfflineMode | boolean | false | Alternativa offline quando os servidores estão inacessíveis. Os resultados então trazem isOffline / isClientOnly. |
serverToken | string | — | 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' | branco | Cor do indicador. |
loadingSize | 'small' | 'medium' | 'large' | 'medium' | Tamanho do indicador. |
loadingDelay | number (ms) | 300 | Exibido 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étodo | Descriçã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
| Callback | Recebe | Quando |
|---|---|---|
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. |
onExpired | passToken | O 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:
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.
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.
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 antespod installemios/.O build do iOS não encontra
CaptchalaSDK
Executepod repo updatee depoispod installemios/. 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+