--- title: SDK React Native description: "SDK React Native da CaptchaLa 1.0.0 (@captcha-la/react-native) para Android e iOS: instalação, configuração, callbacks, expiração do token, indicador de carregamento e validação no servidor." --- # SDK React Native ::: info 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](/sdk/react-native) e o [changelog](/changelog#sdk-1-2-0). ::: **`@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](./android) `la.captcha:captchala` 1.2.0 e [iOS](./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 ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/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](#server-side-validation)). ## 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](https://dash.captcha.la). | | `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](../supported-languages). | | `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](#loading-indicator). | | `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](#token-expiry). | | `onServerTokenExpired` | — | O server token foi rejeitado. Retorne um novo token do seu backend (uma `Promise`) e o SDK continua; retorne `null` para reportar o erro. | ## Expiração do token {#token-expiry} 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 {#loading-indicator} 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 {#server-side-validation} 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": "" } ``` Para emitir o `serverToken` opcional de uso único, o seu backend chama `POST /v1/server/challenge/issue`. Veja a [Referência da API](../api-reference) e [server tokens](../api-reference#server-token), ou use o SDK de servidor [PHP](./server-php) / [Go](./server-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](/sdk/android#webview-too-old). ## Requisitos - React Native 0.73+ (New e Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+