--- title: React-Native-SDK description: "CaptchaLa React-Native-SDK 1.0.0 (@captcha-la/react-native) für Android und iOS: Installation, Konfiguration, Callbacks, Ablauf des Pass-Tokens, Ladeanzeige und serverseitige Validierung." --- # React-Native-SDK ::: info 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](/sdk/react-native) und das [Änderungsprotokoll](/changelog#sdk-1-2-0). ::: **`@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](./android) `la.captcha:captchala` 1.2.0 und [iOS](./ios) `CaptchalaSDK` 1.2.0): Die Challenge, ihre Ladeanzeige und die Geräteprüfungen laufen vollständig nativ. ## Demo auf GitHub ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/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](#server-side-validation)). ## Konfiguration `Captchala.initialize(config)`; nur `appKey` ist erforderlich. | Option | Typ | Standard | Bedeutung | | --- | --- | --- | --- | | `appKey` | string | — | Erforderlich. Ihr App Key aus dem [Dashboard](https://dash.captcha.la). | | `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](../supported-languages). | | `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](#loading-indicator). | | `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](#token-expiry). | | `onServerTokenExpired` | — | Der Server-Token wurde abgelehnt. Geben Sie einen neuen von Ihrem Backend zurück (ein `Promise`), dann fährt das SDK fort; geben Sie `null` zurück, um den Fehler zu melden. | ## Ablauf des Pass-Tokens {#token-expiry} 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 {#loading-indicator} 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 {#server-side-validation} 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": "" } ``` Um den optionalen Einmal-`serverToken` auszustellen, ruft Ihr Backend `POST /v1/server/challenge/issue` auf. Siehe die [API-Referenz](../api-reference) und [Server-Tokens](../api-reference#server-token), oder verwenden Sie das [PHP](./server-php)- bzw. [Go](./server-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)](/sdk/android#webview-too-old). ## Voraussetzungen - React Native 0.73+ (New und Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+