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.
- 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.
- Laden Sie das HarmonyOS-HAR herunter, z. B.
captchala-1.2.0.har. - Vergleichen Sie den SHA-256 der Datei mit dem Wert auf der Download-Seite. Verwenden Sie die Datei nicht, wenn sie abweichen.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- Kopieren Sie die Datei nach
entry/libs/und tragen Sie sie inentry/oh-package.json5ein:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}- Führen Sie
ohpm installim Verzeichnisentryaus oder klicken Sie in DevEco Studio auf Sync Now.
cd entry
ohpm installDas 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:
// 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:
- Ihr Backend stellt für den angemeldeten Benutzer ein einmaliges
server_tokenaus (siehe Server token). - Die App übergibt es an das SDK und öffnet das CAPTCHA.
onSuccessliefert einpassToken; die App sendet es an Ihr Backend.- Ihr Backend validiert das
passToken(siehe Serverseitige Validierung).
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:
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{
"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
| 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) 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. |
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 singletonKonfiguration
| 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<string | null>, 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). |
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) | 300 | Millisekunden bis zum Erscheinen der Anzeige, 0–5000. |
setDebug(boolean) | false | Ausfü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().
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 vonverify()bisonReadyIhre eigene Anzeige.setLoadingColor:#RRGGBBoder#RRGGBBAA, Standard weiß.setLoadingSize:'small','medium'(Standard) oder'large'.setLoadingDelay: Millisekunden,0–5000.
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.
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:
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 installfindet das Paket nicht
Derfile:-Pfad ist relativ zum Modulentry. Prüfen Sie, ob die Datei inentry/libs/liegt und der Dateiname inoh-package.json5exakt übereinstimmt.Nach dem Update wird weiterhin die alte Version verwendet
Löschen Sie das alte.harausentry/libs/, passen Sie die Version imfile:-Pfad an und führen Sieohpm 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.onErrormit einemserver_token_*-Code
Prüfen Sie, obsetActionin der App deractionbeim Ausstellen des Tokens entspricht und obsetOnServerTokenExpiredein 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