--- title: SDK React Native description: "SDK React Native CaptchaLa 1.0.0 (@captcha-la/react-native) pour Android et iOS : installation, configuration, callbacks, expiration du jeton, indicateur de chargement et validation côté serveur." --- # SDK React Native **`@captcha-la/react-native`** ajoute CaptchaLa aux applications React Native sur **Android et iOS**. Version actuelle : **1.0.0**. Il s'agit d'une fine couche au-dessus des SDK natifs ([Android](./android) `la.captcha:captchala` 1.2.0 et [iOS](./ios) `CaptchalaSDK` 1.2.0) : le défi, son indicateur de chargement et les vérifications de l'appareil s'exécutent tous en natif. ## Démo sur GitHub ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/Captcha-La/react-native-demo) — application d'exemple exécutable pour Android et iOS. ::: ## Installation ```bash npm install @captcha-la/react-native cd ios && pod install ``` L'autolinking ajoute le module natif sur les deux plateformes. Recompilez ensuite l'application (`npx react-native run-android` / `run-ios`) ; un simple rechargement du JavaScript ne suffit pas. Le SDK Android provient de Maven Central et le SDK iOS de CocoaPods, tous deux récupérés automatiquement. ## Démarrage rapide ```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(); ``` Validez toujours le pass token sur votre backend avant de lui faire confiance (voir [Validation côté serveur](#server-side-validation)). ## Configuration `Captchala.initialize(config)` ; seul `appKey` est obligatoire. | Option | Type | Par défaut | Description | | --- | --- | --- | --- | | `appKey` | string | — | Obligatoire. Votre app key du [tableau de bord](https://dash.captcha.la). | | `action` | string | `"default"` | Action métier, par ex. `"login"`, `"register"`, `"pay"`. | | `account` | string | — | Identifiant de compte facultatif. | | `lang` | string | auto | Langue de l'interface, par ex. `"zh-CN"`, `"en"`, `"ja"`. Non définie = langue de l'appareil. Voir [Langues prises en charge](../supported-languages). | | `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Suit le système par défaut. | | `title` | string | — | Titre au-dessus du défi. | | `timeout` | number (ms) | `10000` | Délai d'expiration HTTP. | | `retryCount`, `retryDelay` | number | valeur du SDK | Nouvelles tentatives réseau. | | `enableVoice` | boolean | valeur du SDK | Propose le défi audio. | | `enableOfflineMode` | boolean | `false` | Repli hors ligne lorsque les serveurs sont injoignables. Les résultats portent alors `isOffline` / `isClientOnly`. | | `serverToken` | string | — | Jeton à usage unique fourni par votre backend. | | `loadingStyle` | `'spinner' \| 'ring' \| 'dots' \| 'none'` | `'spinner'` | Indicateur pendant le chargement du défi. Voir [Indicateur de chargement](#loading-indicator). | | `loadingColor` | `'#RRGGBB'` / `'#RRGGBBAA'` | blanc | Couleur de l'indicateur. | | `loadingSize` | `'small' \| 'medium' \| 'large'` | `'medium'` | Taille de l'indicateur. | | `loadingDelay` | number (ms) | `300` | Affiché uniquement si le défi met plus longtemps à charger (`0`–`5000`). | Appelez de nouveau `initialize()` pour modifier la configuration, par exemple avec un nouveau `serverToken`. ## API | Méthode | Description | | --- | --- | | `Captchala.initialize(config)` | Configure le SDK natif. Appelez-la avant `verify()` ; un nouvel appel remplace la configuration. | | `Captchala.setCallbacks(callbacks)` | Définit les callbacks (tous facultatifs). Remplace les précédents. | | `Captchala.verify()` | Affiche le défi. Les résultats arrivent via les callbacks. | | `Captchala.dismiss()` | Ferme le défi par programme. | ### Callbacks | Callback | Reçoit | Quand | | --- | --- | --- | | `onReady` | — | Le défi est à l'écran. | | `onSuccess` | `{ passToken, challengeId, isOffline, isClientOnly }` | Vérifié. Envoyez `passToken` à votre backend. | | `onFail` | `{ code, message }` | L'utilisateur n'a pas réussi ; il peut réessayer. | | `onError` | `{ code, message }` | Erreur réseau, de configuration ou système. Basez votre traitement sur `code` ; `message` est un texte de diagnostic en anglais. | | `onClose` | — | L'utilisateur a fermé le défi. | | `onExpired` | `passToken` | Le pass token a expiré avant d'être utilisé. Voir [Expiration du jeton](#token-expiry). | | `onServerTokenExpired` | — | Le server token a été refusé. Renvoyez-en un nouveau depuis votre backend (une `Promise`) et le SDK continue ; renvoyez `null` pour signaler l'erreur. | ## Expiration du jeton {#token-expiry} Le pass token reçu dans `onSuccess` est valable pendant une durée limitée, fixée par le serveur. Si votre formulaire ne l'a pas encore utilisé à ce moment-là, `onExpired` est appelé une fois, afin que vous puissiez effacer le jeton enregistré et demander à l'utilisateur de refaire la vérification au lieu d'envoyer un jeton expiré : ```tsx Captchala.setCallbacks({ onSuccess: (r) => setPassToken(r.passToken), onExpired: () => { setPassToken(null); setNeedsVerify(true); // your button calls Captchala.verify() again }, }); ``` `onExpired` est appelé au plus une fois par succès, et jamais après un nouveau `verify()` ou `initialize()`. ## Indicateur de chargement {#loading-indicator} Pendant le chargement du défi, le SDK natif affiche un petit indicateur sur le voile assombri. Il n'apparaît que si le chargement dure plus longtemps que `loadingDelay` et disparaît dès que le défi s'affiche. `'spinner'` (par défaut) correspond aux rayons classiques, `'ring'` à un arc qui tourne. Avec `'none'`, rien n'est affiché : affichez votre propre indicateur entre `verify()` et `onReady`. ```tsx await Captchala.initialize({ appKey: 'YOUR_APP_KEY', loadingStyle: 'dots', loadingColor: '#3B82F6', loadingSize: 'small', loadingDelay: 500, }); ``` ## Validation côté serveur {#server-side-validation} Envoyez `passToken` à votre backend et validez-le là-bas. Ne placez jamais `X-App-Secret` dans l'application. ```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": "" } ``` Pour émettre le `serverToken` facultatif à usage unique, votre backend appelle `POST /v1/server/challenge/issue`. Voir la [Référence de l'API](../api-reference) et les [server tokens](../api-reference#server-token), ou utilisez le SDK serveur [PHP](./server-php) / [Go](./server-go). ## Dépannage - **`The native module for '@captcha-la/react-native' is not linked`** Recompilez l'application après avoir installé le paquet. Sur iOS, exécutez d'abord `pod install` dans `ios/`. - **La compilation iOS ne trouve pas `CaptchalaSDK`** Exécutez `pod repo update` puis `pod install` dans `ios/`. La cible de déploiement doit être iOS 13 ou supérieure. - **Android `webview_too_old`** Le défi interactif nécessite Android System WebView 63+. Voir le [SDK Android](/sdk/android#webview-too-old). ## Prérequis - React Native 0.73+ (New Architecture et Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+