Skip to content

HarmonyOS SDK ​

SDK 1.2.0

Aktualisiert für SDK 1.2.0. Einige Details sind nur auf Englisch verfügbar: siehe die englische Seite und das Änderungsprotokoll.

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.

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. 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
  1. 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"
  }
}
  1. 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).
  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).
ts
import {
  CaptchalaClient,
  CaptchalaConfigBuilder,
  CaptchalaListener,
  CaptchalaResult,
  CaptchalaError
} from '@captchala/captchala';

@Entry
@Component
struct Login {
  private async verify(): Promise<void> {
    // 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 ​

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; alternativ nutzen Sie das PHP- bzw. Go-Server-SDK.

API-Übersicht ​

SymbolZweck
CaptchalaClient.getClient(uiContext)Singleton-Einstiegspunkt, gebunden an den UIContext Ihrer Seite.
CaptchalaConfigBuilderFluent 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) 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.
CaptchalaResultpassToken, 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.
CaptchalaErrorcode, 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 ​

SetterStandardBedeutung
setAppKey(string)erforderlichIhr App Key aus dem Dashboard.
setAction(string)defaultGeschäftsaktion (login, register, pay, …). Muss zur Action des server_token passen.
setLang(string)'' (auto)Sprache der Challenge, z. B. en, zh-CN.
setTheme(string)autoauto (folgt dem System), light oder dark.
setServerToken(string | null)nullDas von Ihrem Backend ausgestellte server_token.
setOnServerTokenExpired(cb)null() => Promise<string | null>, das ein neues server_token von Ihrem Backend holt.
setTimeout(number)10000Request-Timeout in ms.
setEnableVoice(boolean)trueAudio-Challenge anbieten.
setEnableOfflineMode(boolean)falseAusweichpfad bei Ausfällen erlauben. Ergebnisse tragen isOffline / isClientOnly.
setMaskClosable(boolean)falseTippen auf den Hintergrund schließt den Dialog.
setCollectOdid(boolean)trueEinen Hash der Geräte-ODID melden (siehe Datenschutz).
setLoadingStyle(string)'spinner'Ladeanzeige, siehe Ladeanzeige.
setLoadingColor(string | null)weißFarbe der Anzeige, #RRGGBB oder #RRGGBBAA.
setLoadingSize(string)'medium''small', 'medium' oder 'large'.
setLoadingDelay(number)300Millisekunden bis zum Erscheinen der Anzeige, 0–5000.
setDebug(boolean)falseAusführliches Logging während der Entwicklung.

Ablauf des Pass-Tokens ​

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 ​

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 ​

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": "<result.passToken>", "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.

Datenschutz ​

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 ​

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

Voraussetzungen ​

  • 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

MIT-licensed examples · CaptchaLa is operated independently