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.
- 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.
- Téléchargez le HAR HarmonyOS, par exemple
captchala-1.2.0.har. - Comparez son SHA-256 à la valeur affichée sur la page de téléchargement. S'ils diffèrent, n'utilisez pas le fichier.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- Copiez le fichier dans
entry/libs/et ajoutez-le àentry/oh-package.json5:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}- Lancez
ohpm installdans le répertoireentry, ou cliquez sur Sync Now dans DevEco Studio.
cd entry
ohpm installLe 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 :
// 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 :
- Votre backend émet un
server_tokenà usage unique pour l'utilisateur connecté (voir Server token). - L'application le transmet au SDK et ouvre le CAPTCHA.
onSuccessrenvoie unpassToken; l'application l'envoie à votre backend.- Votre backend valide le
passToken(voir Validation côté serveur).
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 :
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
}
}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
| 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) 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). |
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 singletonConfiguration
| 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<string | null> 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é). |
setLoadingStyle(string) | 'spinner' | Indicateur de chargement, voir Indicateur de chargement. |
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
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().
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 entreverify()etonReady.setLoadingColor:#RRGGBBou#RRGGBBAA, blanc par défaut.setLoadingSize:'small','medium'(par défaut) ou'large'.setLoadingDelay: millisecondes,0–5000.
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.
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 :
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 installne trouve pas le paquet
Le cheminfile:est relatif au moduleentry. Vérifiez que le fichier se trouve dansentry/libs/et que son nom correspond exactement à celui indiqué dansoh-package.json5.L'ancienne version est toujours utilisée après la mise à jour
Supprimez l'ancien.hardeentry/libs/, mettez à jour la version dans le cheminfile:, puis relancezohpm 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.onErroravec un codeserver_token_*
Vérifiez que lesetActionde l'application correspond à l'actionutilisée pour émettre le token et quesetOnServerTokenExpiredrenvoie 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