Skip to content

SDK HarmonyOS ​

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 et le journal des modifications.

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 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. 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
  1. 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"
  }
}
  1. 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).
  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).
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 ​

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 ; vous pouvez aussi utiliser le SDK serveur PHP / Go.

Surface de l'API ​

SymboleRôle
CaptchalaClient.getClient(uiContext)Point d'entrée singleton, lié au UIContext de votre page.
CaptchalaConfigBuilderBuilder 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) 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.
CaptchalaResultpassToken, 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.
CaptchalaErrorcode, 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 ​

SetterDéfautSignification
setAppKey(string)obligatoireVotre App Key issue du tableau de bord.
setAction(string)defaultAction 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)autoauto (suit le système), light ou dark.
setServerToken(string | null)nullLe server_token émis par votre backend.
setOnServerTokenExpired(cb)null() => Promise<string | null> qui récupère un nouveau server_token auprès de votre backend.
setTimeout(number)10000Délai d'expiration des requêtes, en ms.
setEnableVoice(boolean)truePropose le défi audio.
setEnableOfflineMode(boolean)falseAutorise la solution de repli en cas de panne. Ses résultats portent isOffline / isClientOnly.
setMaskClosable(boolean)falseToucher l'arrière-plan ferme la boîte de dialogue.
setCollectOdid(boolean)trueTransmet un hachage de l'ODID de l'appareil (voir Confidentialité).
setLoadingStyle(string)'spinner'Indicateur de chargement, voir Indicateur de chargement.
setLoadingColor(string | null)blancCouleur de l'indicateur, #RRGGBB ou #RRGGBBAA.
setLoadingSize(string)'medium''small', 'medium' ou 'large'.
setLoadingDelay(number)300Millisecondes avant l'apparition de l'indicateur, 0–5000.
setDebug(boolean)falseJournalisation détaillée pendant le développement.

Expiration du jeton ​

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 ​

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 ​

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

Confidentialité ​

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 ​

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

Prérequis ​

  • 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

MIT-licensed examples · CaptchaLa is operated independently