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
npm install @captcha-la/react-native
cd ios && pod installAutolinking 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
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.
| Option | Typ | Standard | Bedeutung |
|---|---|---|---|
appKey | string | — | Erforderlich. Ihr App Key aus dem Dashboard. |
action | string | "default" | Geschäftsaktion, z. B. "login", "register", "pay". |
account | string | — | Optionale Konto-Kennung. |
lang | string | auto | Sprache 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. |
title | string | — | Titel über der Challenge. |
timeout | number (ms) | 10000 | HTTP-Timeout. |
retryCount, retryDelay | number | SDK-Standard | Wiederholungen bei Netzwerkfehlern. |
enableVoice | boolean | SDK-Standard | Audio-Challenge anbieten. |
enableOfflineMode | boolean | false | Offline-Ausweichpfad, wenn die Server nicht erreichbar sind. Ergebnisse tragen dann isOffline / isClientOnly. |
serverToken | string | — | 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. |
loadingDelay | number (ms) | 300 | Wird 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
| Methode | Beschreibung |
|---|---|
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
| Callback | Erhält | Wann |
|---|---|---|
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. |
onExpired | passToken | Der 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:
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.
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.
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 zuerstpod installinios/aus.Der iOS-Build findet
CaptchalaSDKnicht
Führen Siepod repo updateund danachpod installinios/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+