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 la.captcha:captchala 1.2.0 et 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
📦
Captcha-La/react-native-demo — application d'exemple exécutable pour Android et iOS.
Installation
npm install @captcha-la/react-native
cd ios && pod installL'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
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).
Configuration
Captchala.initialize(config) ; seul appKey est obligatoire.
| Option | Type | Par défaut | Description |
|---|---|---|---|
appKey | string | — | Obligatoire. Votre app key du tableau de bord. |
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. |
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. |
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. |
onServerTokenExpired | — | Le server token a été refusé. Renvoyez-en un nouveau depuis votre backend (une Promise<string>) et le SDK continue ; renvoyez null pour signaler l'erreur. |
Expiration du jeton
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é :
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
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.
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
loadingStyle: 'dots',
loadingColor: '#3B82F6',
loadingSize: 'small',
loadingDelay: 500,
});Validation côté serveur
Envoyez passToken à votre backend et validez-le là-bas. Ne placez jamais X-App-Secret dans l'application.
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>" }Pour émettre le serverToken facultatif à usage unique, votre backend appelle POST /v1/server/challenge/issue. Voir la Référence de l'API et les server tokens, ou utilisez le SDK serveur PHP / 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'abordpod installdansios/.La compilation iOS ne trouve pas
CaptchalaSDK
Exécutezpod repo updatepuispod installdansios/. 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.
Prérequis
- React Native 0.73+ (New Architecture et Old Architecture)
- Android 5.0+ (
minSdk 21) - iOS 13+