--- title: SDK HarmonyOS description: "SDK CaptchaLa pour HarmonyOS NEXT (ArkTS) : installation du HAR depuis le tableau de bord, flux de vérification et validation côté serveur." --- # SDK HarmonyOS ::: info SDK 1.2.0 Mis à jour pour le SDK 1.2.0. Certains détails ne sont disponibles qu'en anglais : voir la [page en anglais](/sdk/harmony) et le [journal des modifications](/changelog#sdk-1-2-0). ::: SDK ArkTS pour **HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 ou ultérieur)**, distribué sous la forme d'un unique `.har` (`@captchala/captchala`). Version actuelle : **1.2.0**. Le flux de vérification est le même que celui des SDK Android et iOS : le défi s'ouvre dans une boîte de dialogue au-dessus de votre page, et votre backend valide le `passToken` renvoyé. ::: info HarmonyOS 4.x et versions antérieures exécutent des applications Android. Utilisez le [SDK Android](./android) sur ces appareils. ::: ## Installation Le SDK **n'est pas publié sur ohpm**. Téléchargez le HAR depuis le tableau de bord et ajoutez-le comme dépendance locale. 1. Connectez-vous au tableau de bord et ouvrez [**Téléchargements SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). La même page propose aussi un projet de démo HarmonyOS (code source) à ouvrir dans DevEco Studio. 2. Téléchargez le HAR HarmonyOS, par exemple `captchala-1.2.0.har`. 3. Comparez son SHA-256 à la valeur affichée sur la page de téléchargement. S'ils diffèrent, n'utilisez pas le fichier. ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. Copiez le fichier dans `entry/libs/` et ajoutez-le à `entry/oh-package.json5` : ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. Lancez `ohpm install` dans le répertoire `entry`, ou cliquez sur **Sync Now** dans DevEco Studio. ```bash cd entry ohpm install ``` Le HAR est un build de release obfusqué qui n'expose que l'API publique décrite ci-dessous. Les règles d'obfuscation destinées aux consommateurs sont incluses dans le HAR : votre build de release n'a besoin d'aucune règle keep supplémentaire. ### Permissions Le SDK n'utilise qu'une permission, `ohos.permission.INTERNET`. Il ne demande jamais de permission à l'exécution et n'affiche aucune invite. Vérifiez que votre module entry la déclare : ```json5 // entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } } ``` ### Mise à jour Téléchargez le nouveau HAR, copiez-le dans `entry/libs/`, modifiez la version dans le chemin `file:` de `entry/oh-package.json5`, supprimez l'ancien `.har`, puis relancez `ohpm install`. ## Démarrage rapide Le flux : 1. Votre backend émet un `server_token` à usage unique pour l'utilisateur connecté (voir [Server token](#server-token)). 2. L'application le transmet au SDK et ouvre le CAPTCHA. 3. `onSuccess` renvoie un `passToken` ; l'application l'envoie à votre backend. 4. Votre backend valide le `passToken` (voir [Validation côté serveur](#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} C'est votre backend, et non l'application, qui génère le `server_token` en appelant `/v1/server/challenge/issue` avec votre `X-App-Key` + `X-App-Secret`. Passez `bind_uid` avec votre propre identifiant utilisateur pour que le token, et le `passToken` qui en découle, appartiennent à cet utilisateur : ```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 } } ``` Renvoyez `data.server_token` (préfixe `sct_`) à l'application. `action` doit correspondre à la valeur passée à `setAction`. Avec `setOnServerTokenExpired`, le SDK récupère lui-même un nouveau token et réessaie lorsqu'un token est refusé pendant le défi ; renvoyez `null` pour obtenir l'erreur d'origine. Les options de liaison d'identité (`bind_uid`, `bind_ip`) se définissent uniquement sur votre serveur, à l'émission du token. L'application ne les envoie jamais. Tous les paramètres sont décrits dans la [Référence de l'API](../api-reference#server-token) ; vous pouvez aussi utiliser le SDK serveur [PHP](./server-php) / [Go](./server-go). ## Surface de l'API {#api-surface} | Symbole | Rôle | | --- | --- | | `CaptchalaClient.getClient(uiContext)` | Point d'entrée singleton, lié au `UIContext` de votre page. | | `CaptchalaConfigBuilder` | Builder fluide pour la configuration (voir le tableau ci-dessous). `build()` renvoie un `CaptchalaConfig`. | | `init(config)` | Applique la configuration. Renvoie le client, ce qui permet d'enchaîner les appels. | | `setListener(listener)` | Enregistre un `CaptchalaListener`. Seul `onSuccess` est obligatoire ; `onReady`, `onFail`, `onError`, `onClose` et `onExpired` (voir [Expiration du jeton](#token-expiry)) sont facultatifs. | | `verify()` | Ouvre la boîte de dialogue du CAPTCHA. Le résultat arrive via le listener. | | `refresh()` / `cancel()` / `dismiss()` | Recharge le défi en cours / arrête le flux et ferme la boîte de dialogue / ferme la boîte de dialogue. | | `CaptchalaClient.destroy()` | Libère le singleton. | | `CaptchalaResult` | `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. Envoyez `passToken` à votre backend. `ttl` est obsolète depuis la 1.2.0 : le serveur décide de la durée de vie du jeton et peut la modifier ; utilisez `onExpired`. | | `CaptchalaError` | `code`, `message`, `detail`. Transmis à `onFail` (l'utilisateur peut réessayer) et à `onError` (erreur réseau, de configuration ou système). | ```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 ``` ### Configuration {#configuration} | Setter | Défaut | Signification | | --- | --- | --- | | `setAppKey(string)` | obligatoire | Votre App Key issue du tableau de bord. | | `setAction(string)` | `default` | Action métier (`login`, `register`, `pay`, …). Doit correspondre à l'action du `server_token`. | | `setLang(string)` | `''` (auto) | Langue du défi, par ex. `en`, `zh-CN`. | | `setTheme(string)` | `auto` | `auto` (suit le système), `light` ou `dark`. | | `setServerToken(string \| null)` | `null` | Le `server_token` émis par votre backend. | | `setOnServerTokenExpired(cb)` | `null` | `() => Promise` qui récupère un nouveau `server_token` auprès de votre backend. | | `setTimeout(number)` | `10000` | Délai d'expiration des requêtes, en ms. | | `setEnableVoice(boolean)` | `true` | Propose le défi audio. | | `setEnableOfflineMode(boolean)` | `false` | Autorise la solution de repli en cas de panne. Ses résultats portent `isOffline` / `isClientOnly`. | | `setMaskClosable(boolean)` | `false` | Toucher l'arrière-plan ferme la boîte de dialogue. | | `setCollectOdid(boolean)` | `true` | Transmet un hachage de l'ODID de l'appareil (voir [Confidentialité](#privacy)). | | `setLoadingStyle(string)` | `'spinner'` | Indicateur de chargement, voir [Indicateur de chargement](#loading-indicator). | | `setLoadingColor(string \| null)` | blanc | Couleur de l'indicateur, `#RRGGBB` ou `#RRGGBBAA`. | | `setLoadingSize(string)` | `'medium'` | `'small'`, `'medium'` ou `'large'`. | | `setLoadingDelay(number)` | `300` | Millisecondes avant l'apparition de l'indicateur, `0`–`5000`. | | `setDebug(boolean)` | `false` | Journalisation détaillée pendant le développement. | ## Expiration du jeton {#token-expiry} Le pass token reçu dans `onSuccess` est valable pendant une durée limitée, fixée par le serveur. Si votre page ne l'a pas encore utilisé à ce moment-là, `onExpired(passToken)` du listener est appelé une fois, afin que vous puissiez effacer le jeton enregistré et demander à l'utilisateur de refaire la vérification au lieu d'envoyer un jeton expiré. Lancez une nouvelle vérification avec `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` n'est pas appelé après un nouveau `verify()`, `init()` ou `destroy()`. Disponible depuis la 1.2.0. ## Indicateur de chargement {#loading-indicator} Pendant le chargement du défi, le SDK affiche un petit indicateur sur le voile assombri. Il n'apparaît que si le chargement dure plus longtemps que `setLoadingDelay` (300 ms par défaut), et disparaît dès que le défi s'affiche. Disponible depuis la 1.2.0. - `setLoadingStyle` : `'spinner'` (par défaut, rayons), `'ring'` (un arc qui tourne), `'dots'` ou `'none'`. Avec `'none'`, rien n'est affiché : affichez votre propre indicateur entre `verify()` et `onReady`. - `setLoadingColor` : `#RRGGBB` ou `#RRGGBBAA`, blanc par défaut. - `setLoadingSize` : `'small'`, `'medium'` (par défaut) ou `'large'`. - `setLoadingDelay` : millisecondes, `0`–`5000`. ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## Validation côté serveur {#server-side-validation} Transmettez `result.passToken` à votre backend et validez-le auprès de l'API CaptchaLa. Ne placez jamais `X-App-Secret` dans l'application. ```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" } ``` N'acceptez la requête que si `data.valid` vaut `true` et que `data.uid` correspond à l'utilisateur pour lequel vous avez émis le `server_token`. Les tokens sont à usage unique. La réponse complète et les codes d'erreur sont décrits dans la [Référence de l'API](../api-reference). ## Confidentialité {#privacy} Le SDK lit un ensemble d'attributs de l'appareil qui ne nécessitent aucune permission (modèle, version du système, écran, paramètres régionaux, fuseau horaire, etc.) et ne les utilise que pour la vérification et la prévention de la fraude. Par défaut, il transmet aussi un hachage SHA-256 tronqué de l'ODID de l'appareil, jamais la valeur brute. Aucun OAID, UDID, numéro de série ni donnée de compte n'est collecté. Pour désactiver le hachage de l'ODID : ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setCollectOdid(false) // the ODID is never read .build(); ``` Si vous le laissez activé, déclarez un identifiant d'appareil utilisé pour la prévention de la fraude dans votre politique de confidentialité et dans l'étiquette de confidentialité AppGallery. ## Dépannage {#troubleshooting} - **`ohpm install` ne trouve pas le paquet** Le chemin `file:` est relatif au module `entry`. Vérifiez que le fichier se trouve dans `entry/libs/` et que son nom correspond exactement à celui indiqué dans `oh-package.json5`. - **L'ancienne version est toujours utilisée après la mise à jour** Supprimez l'ancien `.har` de `entry/libs/`, mettez à jour la version dans le chemin `file:`, puis relancez `ohpm install` (ou **Sync Now**). - **Le SHA-256 ne correspond pas** Retéléchargez le HAR depuis [**Téléchargements SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). Ne livrez pas un fichier dont la somme de contrôle diffère de celle du tableau de bord. - **`onError` avec un code `server_token_*`** Vérifiez que le `setAction` de l'application correspond à l'`action` utilisée pour émettre le token et que `setOnServerTokenExpired` renvoie un nouveau token. - **L'appareil fonctionne sous HarmonyOS 4.x ou antérieur** Non pris en charge. Ces appareils exécutent des applications Android ; utilisez le [SDK Android](./android). ## Prérequis {#requirements} - HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) ou ultérieur, modèle Stage - Types d'appareils : téléphone, tablette, 2-en-1 - ABI : `arm64-v8a`, `x86_64` (émulateur) - `ohos.permission.INTERNET`