Skip to content

React-Native-SDK ​

SDK 1.2.0

React Native 1.0.0, aufgebaut auf SDK 1.2.0. Einige Details sind nur auf Englisch verfügbar: siehe die englische Seite und das Änderungsprotokoll.

@captcha-la/react-native bindet CaptchaLa in React-Native-Apps unter Android und iOS ein. Aktuelle Version: 1.0.0. Das Paket ist eine dünne Brücke zu den nativen SDKs (Android la.captcha:captchala 1.2.0 und iOS CaptchalaSDK 1.2.0): Die Challenge, ihre Ladeanzeige und die Geräteprüfungen laufen vollständig nativ.

Demo auf GitHub ​

📦

Captcha-La/react-native-demo — lauffähige Beispiel-App für Android und iOS.

Installation ​

bash
npm install @captcha-la/react-native
cd ios && pod install

Autolinking fügt das native Modul auf beiden Plattformen hinzu. Bauen Sie die App danach neu (npx react-native run-android / run-ios); ein Neuladen des JavaScript-Codes reicht nicht aus. Das Android-SDK kommt von Maven Central, das iOS-SDK von CocoaPods; beide werden automatisch eingebunden.

Schnellstart ​

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();

Validieren Sie den Pass-Token immer auf Ihrem Backend, bevor Sie ihm vertrauen (siehe Serverseitige Validierung).

Konfiguration ​

Captchala.initialize(config); nur appKey ist erforderlich.

OptionTypStandardBedeutung
appKeystring—Erforderlich. Ihr App Key aus dem Dashboard.
actionstring"default"Geschäftsaktion, z. B. "login", "register", "pay".
accountstring—Optionale Konto-Kennung.
langstringautoSprache der Oberfläche, z. B. "zh-CN", "en", "ja". Nicht gesetzt = Gerätesprache. Siehe Unterstützte Sprachen.
theme'auto' | 'light' | 'dark''auto'Folgt standardmäßig dem System.
titlestring—Titel über der Challenge.
timeoutnumber (ms)10000HTTP-Timeout.
retryCount, retryDelaynumberSDK-StandardWiederholungen bei Netzwerkfehlern.
enableVoicebooleanSDK-StandardAudio-Challenge anbieten.
enableOfflineModebooleanfalseOffline-Ausweichpfad, wenn die Server nicht erreichbar sind. Ergebnisse tragen dann isOffline / isClientOnly.
serverTokenstring—Einmal-Token von Ihrem Backend.
loadingStyle'spinner' | 'ring' | 'dots' | 'none''spinner'Anzeige, während die Challenge lädt. Siehe Ladeanzeige.
loadingColor'#RRGGBB' / '#RRGGBBAA'weißFarbe der Anzeige.
loadingSize'small' | 'medium' | 'large''medium'Größe der Anzeige.
loadingDelaynumber (ms)300Wird nur angezeigt, wenn die Challenge länger als diese Zeit braucht (0–5000).

Rufen Sie initialize() erneut auf, um die Konfiguration zu ändern, zum Beispiel mit einem neuen serverToken.

API ​

MethodeBeschreibung
Captchala.initialize(config)Konfiguriert das native SDK. Vor verify() aufrufen; ein erneuter Aufruf ersetzt die Konfiguration.
Captchala.setCallbacks(callbacks)Setzt die Callbacks (alle optional). Ersetzt zuvor gesetzte.
Captchala.verify()Zeigt die Challenge. Ergebnisse kommen über die Callbacks.
Captchala.dismiss()Schließt die Challenge programmatisch.

Callbacks ​

CallbackErhältWann
onReady—Die Challenge wird angezeigt.
onSuccess{ passToken, challengeId, isOffline, isClientOnly }Verifiziert. Senden Sie passToken an Ihr Backend.
onFail{ code, message }Der Benutzer hat nicht bestanden und kann es erneut versuchen.
onError{ code, message }Netzwerk-, Konfigurations- oder Systemfehler. Verzweigen Sie anhand von code; message ist englischer Diagnosetext.
onClose—Der Benutzer hat die Challenge geschlossen.
onExpiredpassTokenDer Pass-Token ist abgelaufen, bevor er verwendet wurde. Siehe Ablauf des Pass-Tokens.
onServerTokenExpired—Der Server-Token wurde abgelehnt. Geben Sie einen neuen von Ihrem Backend zurück (ein Promise<string>), dann fährt das SDK fort; geben Sie null zurück, um den Fehler zu melden.

Ablauf des Pass-Tokens ​

Der Pass-Token aus onSuccess ist nur begrenzte Zeit gültig; die Dauer legt der Server fest. Hat Ihr Formular ihn bis dahin nicht verwendet, wird onExpired einmal aufgerufen. So können Sie den gespeicherten Token verwerfen und den Benutzer erneut verifizieren lassen, statt einen abgelaufenen Token abzusenden:

tsx
Captchala.setCallbacks({
  onSuccess: (r) => setPassToken(r.passToken),
  onExpired: () => {
    setPassToken(null);
    setNeedsVerify(true);        // your button calls Captchala.verify() again
  },
});

onExpired wird höchstens einmal pro Erfolg aufgerufen und nicht nach einem neuen verify() oder initialize().

Ladeanzeige ​

Während die Challenge lädt, zeigt das native SDK eine kleine Anzeige auf dem abgedunkelten Hintergrund. Sie erscheint nur, wenn das Laden länger als loadingDelay dauert, und verschwindet, sobald die Challenge angezeigt wird. 'spinner' (Standard) sind die klassischen Speichen, 'ring' ein rotierender Bogen. Bei 'none' wird nichts angezeigt: Zeigen Sie dann von verify() bis onReady Ihre eigene Anzeige.

tsx
await Captchala.initialize({
  appKey: 'YOUR_APP_KEY',
  loadingStyle: 'dots',
  loadingColor: '#3B82F6',
  loadingSize: 'small',
  loadingDelay: 500,
});

Serverseitige Validierung ​

Senden Sie passToken an Ihr Backend und validieren Sie ihn dort. Legen Sie X-App-Secret niemals in der App ab.

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>" }

Um den optionalen Einmal-serverToken auszustellen, ruft Ihr Backend POST /v1/server/challenge/issue auf. Siehe die API-Referenz und Server-Tokens, oder verwenden Sie das PHP- bzw. Go-Server-SDK.

Fehlerbehebung ​

  • The native module for '@captcha-la/react-native' is not linked
    Bauen Sie die App nach der Installation des Pakets neu. Unter iOS führen Sie zuerst pod install in ios/ aus.

  • Der iOS-Build findet CaptchalaSDK nicht
    Führen Sie pod repo update und danach pod install in ios/ aus. Das Deployment-Target muss iOS 13 oder höher sein.

  • Android webview_too_old
    Die interaktive Challenge benötigt Android System WebView 63+. Siehe das Android-SDK (Englisch).

Voraussetzungen ​

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

MIT-licensed examples · CaptchaLa is operated independently