Skip to content

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 ​

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).

Configuration ​

Captchala.initialize(config) ; seul appKey est obligatoire.

OptionTypePar défautDescription
appKeystring—Obligatoire. Votre app key du tableau de bord.
actionstring"default"Action métier, par ex. "login", "register", "pay".
accountstring—Identifiant de compte facultatif.
langstringautoLangue 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.
titlestring—Titre au-dessus du défi.
timeoutnumber (ms)10000Délai d'expiration HTTP.
retryCount, retryDelaynumbervaleur du SDKNouvelles tentatives réseau.
enableVoicebooleanvaleur du SDKPropose le défi audio.
enableOfflineModebooleanfalseRepli hors ligne lorsque les serveurs sont injoignables. Les résultats portent alors isOffline / isClientOnly.
serverTokenstring—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'blancCouleur de l'indicateur.
loadingSize'small' | 'medium' | 'large''medium'Taille de l'indicateur.
loadingDelaynumber (ms)300Affiché 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éthodeDescription
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 ​

CallbackReçoitQuand
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.
onExpiredpassTokenLe 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é :

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 ​

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 ​

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": "<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'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.

Prérequis ​

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

MIT-licensed examples · CaptchaLa is operated independently