--- title: HarmonyOS SDK description: "CaptchaLa SDK für HarmonyOS NEXT (ArkTS): HAR-Installation aus dem Dashboard, Verifizierungsablauf und serverseitige Validierung." --- # HarmonyOS SDK ::: info SDK 1.2.0 Aktualisiert für SDK 1.2.0. Einige Details sind nur auf Englisch verfügbar: siehe die [englische Seite](/sdk/harmony) und das [Änderungsprotokoll](/changelog#sdk-1-2-0). ::: ArkTS-SDK für **HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 und neuer)**, ausgeliefert als einzelnes `.har` (`@captchala/captchala`). Aktuelle Version: **1.2.0**. Der Ablauf entspricht dem der Android- und iOS-SDKs: Die Challenge öffnet sich als Dialog über Ihrer Seite, und Ihr Backend validiert das zurückgegebene `passToken`. ::: info HarmonyOS 4.x und älter führt Android-Apps aus. Verwenden Sie dort das [Android-SDK](./android). ::: ## Installation Das SDK ist **nicht auf ohpm veröffentlicht**. Sie laden das HAR aus dem Dashboard herunter und binden es als lokale Abhängigkeit ein. 1. Melden Sie sich im Dashboard an und öffnen Sie [**SDK-Downloads**](https://dash.captcha.la/sdk-downloads?platform=harmony). Auf derselben Seite gibt es auch ein HarmonyOS-Demoprojekt (Quellcode) zum Öffnen in DevEco Studio. 2. Laden Sie das HarmonyOS-HAR herunter, z. B. `captchala-1.2.0.har`. 3. Vergleichen Sie den SHA-256 der Datei mit dem Wert auf der Download-Seite. Verwenden Sie die Datei nicht, wenn sie abweichen. ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. Kopieren Sie die Datei nach `entry/libs/` und tragen Sie sie in `entry/oh-package.json5` ein: ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. Führen Sie `ohpm install` im Verzeichnis `entry` aus oder klicken Sie in DevEco Studio auf **Sync Now**. ```bash cd entry ohpm install ``` Das HAR ist ein obfuskierter Release-Build, der nur die unten aufgeführte öffentliche API bereitstellt. Die Obfuskierungsregeln für Konsumenten sind im HAR enthalten, Ihr Release-Build braucht also keine zusätzlichen Keep-Regeln. ### Berechtigungen Das SDK verwendet eine einzige Berechtigung, `ohos.permission.INTERNET`. Es fordert nie eine Laufzeitberechtigung an und zeigt keine Abfrage. Stellen Sie sicher, dass Ihr Entry-Modul sie deklariert: ```json5 // entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } } ``` ### Aktualisieren Laden Sie das neue HAR herunter, kopieren Sie es nach `entry/libs/`, ändern Sie die Version im `file:`-Pfad in `entry/oh-package.json5`, löschen Sie das alte `.har` und führen Sie `ohpm install` erneut aus. ## Schnellstart Der Ablauf: 1. Ihr Backend stellt für den angemeldeten Benutzer ein einmaliges `server_token` aus (siehe [Server token](#server-token)). 2. Die App übergibt es an das SDK und öffnet das CAPTCHA. 3. `onSuccess` liefert ein `passToken`; die App sendet es an Ihr Backend. 4. Ihr Backend validiert das `passToken` (siehe [Serverseitige Validierung](#server-side-validation)). ```ts import { CaptchalaClient, CaptchalaConfigBuilder, CaptchalaListener, CaptchalaResult, CaptchalaError } from '@captchala/captchala'; @Entry @Component struct Login { private async verify(): Promise { // 1. Fetch a one-shot server_token from YOUR backend // (which calls the CaptchaLa server API with X-App-Key + X-App-Secret). const serverToken: string | null = await fetchServerTokenFromYourBackend(); // 2. Listen for terminal events. const listener: CaptchalaListener = { onReady: (): void => { /* challenge presented */ }, onSuccess: (result: CaptchalaResult): void => { // Send result.passToken to your backend for validation. sendToBackend(result.passToken); }, onFail: (error: CaptchalaError): void => { /* wrong answer, the user may retry */ }, onError: (error: CaptchalaError): void => { /* network / configuration error */ }, onClose: (): void => { /* user dismissed */ }, onExpired: (passToken: string): void => { /* the pass token expired: ask the user to verify again */ } }; // 3. Build the config. const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setAction('login') // login, register, pay, … // .setLang('ja') // optional: default is the device language // .setTheme('light') // optional: 'auto' (default, follows the system) | 'light' | 'dark' .setServerToken(serverToken) .setOnServerTokenExpired(() => fetchServerTokenFromYourBackend()) .build(); // 4. Open the CAPTCHA. The result is delivered through the listener. CaptchalaClient.getClient(this.getUIContext()) .init(config) .setListener(listener) .verify(); } build() { Button('Verify').onClick(() => { this.verify(); }) } } ``` ## Server token {#server-token} Das `server_token` erzeugt Ihr Backend, nicht die App: Es ruft `/v1/server/challenge/issue` mit `X-App-Key` + `X-App-Secret` auf. Übergeben Sie `bind_uid` mit Ihrer eigenen Benutzer-ID, damit das Token und das daraus entstehende `passToken` diesem Benutzer gehören: ```bash POST https://verify.captcha.la/v1/server/challenge/issue X-App-Key: YOUR_APP_KEY X-App-Secret: YOUR_APP_SECRET Content-Type: application/x-www-form-urlencoded action=login&ttl=300&max_uses=1&bind_uid=user_12345 ``` ```json { "code": 0, "data": { "server_token": "sct_xxxxxxxxxxxx", "expires_in": 300, "issued_at": 1713600000 } } ``` Geben Sie `data.server_token` (Präfix `sct_`) an die App zurück. `action` muss dem Wert von `setAction` entsprechen. Mit `setOnServerTokenExpired` holt das SDK selbstständig ein neues Token und versucht es erneut, wenn ein Token während der Challenge abgelehnt wird; geben Sie `null` zurück, um stattdessen den ursprünglichen Fehler zu erhalten. Optionen zur Identitätsbindung (`bind_uid`, `bind_ip`) werden ausschließlich auf Ihrem Server beim Ausstellen des Tokens gesetzt. Die App sendet sie nie. Alle Parameter finden Sie in der [API-Referenz](../api-reference#server-token); alternativ nutzen Sie das [PHP](./server-php)- bzw. [Go](./server-go)-Server-SDK. ## API-Übersicht {#api-surface} | Symbol | Zweck | | --- | --- | | `CaptchalaClient.getClient(uiContext)` | Singleton-Einstiegspunkt, gebunden an den `UIContext` Ihrer Seite. | | `CaptchalaConfigBuilder` | Fluent Builder für die Konfiguration (siehe Tabelle unten). `build()` liefert eine `CaptchalaConfig`. | | `init(config)` | Wendet die Konfiguration an. Gibt den Client zurück, Aufrufe lassen sich also verketten. | | `setListener(listener)` | Registriert einen `CaptchalaListener`. Nur `onSuccess` ist Pflicht; `onReady`, `onFail`, `onError`, `onClose` und `onExpired` (siehe [Ablauf des Pass-Tokens](#token-expiry)) sind optional. | | `verify()` | Öffnet den CAPTCHA-Dialog. Das Ergebnis kommt über den Listener. | | `refresh()` / `cancel()` / `dismiss()` | Aktuelle Challenge neu laden / Ablauf abbrechen und Dialog schließen / Dialog schließen. | | `CaptchalaClient.destroy()` | Gibt das Singleton frei. | | `CaptchalaResult` | `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. Senden Sie `passToken` an Ihr Backend. `ttl` ist seit 1.2.0 veraltet: Der Server legt die Gültigkeitsdauer des Tokens fest und kann sie ändern; verwenden Sie `onExpired`. | | `CaptchalaError` | `code`, `message`, `detail`. Wird an `onFail` (der Benutzer kann es erneut versuchen) und `onError` (Netzwerk-, Konfigurations- oder Systemfehler) übergeben. | ```ts const client = CaptchalaClient.getClient(this.getUIContext()); client.refresh(); // reload the current challenge client.cancel(); // stop the flow and close the dialog client.dismiss(); // close the dialog CaptchalaClient.destroy(); // release the singleton ``` ### Konfiguration {#configuration} | Setter | Standard | Bedeutung | | --- | --- | --- | | `setAppKey(string)` | erforderlich | Ihr App Key aus dem Dashboard. | | `setAction(string)` | `default` | Geschäftsaktion (`login`, `register`, `pay`, …). Muss zur Action des `server_token` passen. | | `setLang(string)` | `''` (auto) | Sprache der Challenge, z. B. `en`, `zh-CN`. | | `setTheme(string)` | `auto` | `auto` (folgt dem System), `light` oder `dark`. | | `setServerToken(string \| null)` | `null` | Das von Ihrem Backend ausgestellte `server_token`. | | `setOnServerTokenExpired(cb)` | `null` | `() => Promise`, das ein neues `server_token` von Ihrem Backend holt. | | `setTimeout(number)` | `10000` | Request-Timeout in ms. | | `setEnableVoice(boolean)` | `true` | Audio-Challenge anbieten. | | `setEnableOfflineMode(boolean)` | `false` | Ausweichpfad bei Ausfällen erlauben. Ergebnisse tragen `isOffline` / `isClientOnly`. | | `setMaskClosable(boolean)` | `false` | Tippen auf den Hintergrund schließt den Dialog. | | `setCollectOdid(boolean)` | `true` | Einen Hash der Geräte-ODID melden (siehe [Datenschutz](#privacy)). | | `setLoadingStyle(string)` | `'spinner'` | Ladeanzeige, siehe [Ladeanzeige](#loading-indicator). | | `setLoadingColor(string \| null)` | weiß | Farbe der Anzeige, `#RRGGBB` oder `#RRGGBBAA`. | | `setLoadingSize(string)` | `'medium'` | `'small'`, `'medium'` oder `'large'`. | | `setLoadingDelay(number)` | `300` | Millisekunden bis zum Erscheinen der Anzeige, `0`–`5000`. | | `setDebug(boolean)` | `false` | Ausführliches Logging während der Entwicklung. | ## Ablauf des Pass-Tokens {#token-expiry} Das `passToken` aus `onSuccess` ist nur begrenzte Zeit gültig; die Dauer legt der Server fest. Hat Ihre Seite es bis dahin nicht verwendet, wird `onExpired(passToken)` des Listeners einmal aufgerufen. So können Sie das gespeicherte Token verwerfen und den Benutzer erneut verifizieren lassen, statt ein abgelaufenes Token abzusenden. Eine neue Verifizierung starten Sie mit `verify()`. ```ts const listener: CaptchalaListener = { onSuccess: (result: CaptchalaResult): void => { this.passToken = result.passToken; }, onExpired: (passToken: string): void => { this.passToken = ''; this.showVerifyAgain = true; // your button calls client.verify() again } }; ``` `onExpired` wird nach einem neuen `verify()`, `init()` oder `destroy()` nicht aufgerufen. Verfügbar ab 1.2.0. ## Ladeanzeige {#loading-indicator} Während die Challenge lädt, zeigt das SDK eine kleine Anzeige auf dem abgedunkelten Hintergrund. Sie erscheint nur, wenn das Laden länger als `setLoadingDelay` (Standard 300 ms) dauert, und verschwindet, sobald die Challenge angezeigt wird. Verfügbar ab 1.2.0. - `setLoadingStyle`: `'spinner'` (Standard, Speichen), `'ring'` (ein rotierender Bogen), `'dots'` oder `'none'`. Bei `'none'` wird nichts angezeigt: Zeigen Sie dann von `verify()` bis `onReady` Ihre eigene Anzeige. - `setLoadingColor`: `#RRGGBB` oder `#RRGGBBAA`, Standard weiß. - `setLoadingSize`: `'small'`, `'medium'` (Standard) oder `'large'`. - `setLoadingDelay`: Millisekunden, `0`–`5000`. ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## Serverseitige Validierung {#server-side-validation} Leiten Sie `result.passToken` an Ihr Backend weiter und validieren Sie es gegen die CaptchaLa-API. 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": "", "expected_action": "login" } ``` Akzeptieren Sie die Anfrage nur, wenn `data.valid` `true` ist und `data.uid` dem Benutzer entspricht, für den Sie das `server_token` ausgestellt haben. Tokens sind einmalig verwendbar. Die vollständige Antwort und alle Fehlercodes finden Sie in der [API-Referenz](../api-reference). ## Datenschutz {#privacy} Das SDK liest Geräteattribute, die keine Berechtigung erfordern (Modell, OS-Version, Bildschirm, Gebietsschema, Zeitzone u. Ä.), und nutzt sie ausschließlich zur Verifizierung und Betrugsprävention. Standardmäßig meldet es außerdem einen gekürzten SHA-256-Hash der Geräte-ODID, nie den Rohwert. OAID, UDID, Seriennummer und Kontodaten werden nicht erfasst. So schalten Sie den ODID-Hash ab: ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setCollectOdid(false) // the ODID is never read .build(); ``` Wenn Sie ihn aktiviert lassen, geben Sie in Ihrer Datenschutzerklärung und im AppGallery-Datenschutzlabel eine zur Betrugsprävention genutzte Gerätekennung an. ## Fehlerbehebung {#troubleshooting} - **`ohpm install` findet das Paket nicht** Der `file:`-Pfad ist relativ zum Modul `entry`. Prüfen Sie, ob die Datei in `entry/libs/` liegt und der Dateiname in `oh-package.json5` exakt übereinstimmt. - **Nach dem Update wird weiterhin die alte Version verwendet** Löschen Sie das alte `.har` aus `entry/libs/`, passen Sie die Version im `file:`-Pfad an und führen Sie `ohpm install` (oder **Sync Now**) erneut aus. - **SHA-256 stimmt nicht überein** Laden Sie das HAR erneut unter [**SDK-Downloads**](https://dash.captcha.la/sdk-downloads?platform=harmony) herunter. Liefern Sie keine Datei aus, deren Prüfsumme nicht zum Dashboard passt. - **`onError` mit einem `server_token_*`-Code** Prüfen Sie, ob `setAction` in der App der `action` beim Ausstellen des Tokens entspricht und ob `setOnServerTokenExpired` ein neues Token liefert. - **Das Gerät läuft mit HarmonyOS 4.x oder älter** Nicht unterstützt. Diese Geräte führen Android-Apps aus; verwenden Sie das [Android-SDK](./android). ## Voraussetzungen {#requirements} - HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) oder neuer, Stage-Modell - Gerätetypen: Smartphone, Tablet, 2-in-1 - ABIs: `arm64-v8a`, `x86_64` (Emulator) - `ohos.permission.INTERNET`