--- title: SDK HarmonyOS description: "SDK da CaptchaLa para HarmonyOS NEXT (ArkTS): instalação do HAR pelo painel, fluxo de verificação e validação no servidor." --- # SDK HarmonyOS ::: info SDK 1.2.0 Atualizado para o SDK 1.2.0. Alguns detalhes estão disponíveis apenas em inglês: veja a [página em inglês](/sdk/harmony) e o [changelog](/changelog#sdk-1-2-0). ::: SDK em ArkTS para **HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 ou superior)**, distribuído como um único `.har` (`@captchala/captchala`). Versão atual: **1.2.0**. O fluxo de verificação é o mesmo dos SDKs Android e iOS: o desafio abre em uma caixa de diálogo sobre a sua página, e o seu backend valida o `passToken` retornado. ::: info HarmonyOS 4.x e versões anteriores executam apps Android. Nesses aparelhos, use o [SDK Android](./android). ::: ## Instalação O SDK **não está publicado no ohpm**. Baixe o HAR pelo painel e adicione-o como dependência local. 1. Entre no painel e abra [**Downloads de SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). A mesma página também oferece um projeto de demonstração do HarmonyOS (código-fonte) para abrir no DevEco Studio. 2. Baixe o HAR do HarmonyOS, por exemplo `captchala-1.2.0.har`. 3. Compare o SHA-256 do arquivo com o valor exibido na página de download. Se forem diferentes, não use o arquivo. ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. Copie o arquivo para `entry/libs/` e adicione-o ao `entry/oh-package.json5`: ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. Execute `ohpm install` no diretório `entry` ou clique em **Sync Now** no DevEco Studio. ```bash cd entry ohpm install ``` O HAR é um build de release ofuscado que expõe apenas a API pública descrita abaixo. As regras de ofuscação para o consumidor já vêm dentro do HAR, então o seu build de release não precisa de regras keep extras. ### Permissões O SDK usa uma única permissão, `ohos.permission.INTERNET`. Ele nunca solicita nem exibe pedidos de permissão em tempo de execução. Confirme que o seu módulo entry a declara: ```json5 // entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } } ``` ### Atualização Baixe o novo HAR, copie-o para `entry/libs/`, altere a versão no caminho `file:` do `entry/oh-package.json5`, apague o `.har` antigo e execute `ohpm install` novamente. ## Início rápido O fluxo: 1. O seu backend emite um `server_token` de uso único para o usuário conectado (veja [Server token](#server-token)). 2. O app repassa o token ao SDK e abre o CAPTCHA. 3. `onSuccess` retorna um `passToken`; o app o envia ao seu backend. 4. O seu backend valida o `passToken` (veja [Validação no servidor](#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} Quem gera o `server_token` é o seu backend, não o app: ele chama `/v1/server/challenge/issue` com o seu `X-App-Key` + `X-App-Secret`. Envie `bind_uid` com o ID do usuário no seu sistema para que o token, e o `passToken` gerado a partir dele, pertençam a esse usuário: ```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 } } ``` Retorne `data.server_token` (prefixo `sct_`) ao app. `action` precisa ser igual ao valor passado em `setAction`. Com `setOnServerTokenExpired`, o SDK busca um token novo e tenta de novo sozinho quando um token é rejeitado durante o desafio; retorne `null` para receber o erro original. As opções de vínculo de identidade (`bind_uid`, `bind_ip`) são definidas apenas no seu servidor, na emissão do token. O app nunca as envia. Veja todos os parâmetros na [Referência da API](../api-reference#server-token) ou use o SDK de servidor [PHP](./server-php) / [Go](./server-go). ## Superfície da API {#api-surface} | Símbolo | Finalidade | | --- | --- | | `CaptchalaClient.getClient(uiContext)` | Ponto de entrada singleton, vinculado ao `UIContext` da sua página. | | `CaptchalaConfigBuilder` | Builder fluente para a configuração (veja a tabela abaixo). `build()` retorna um `CaptchalaConfig`. | | `init(config)` | Aplica a configuração. Retorna o cliente, permitindo encadear chamadas. | | `setListener(listener)` | Registra um `CaptchalaListener`. Só `onSuccess` é obrigatório; `onReady`, `onFail`, `onError`, `onClose` e `onExpired` (veja [Expiração do token](#token-expiry)) são opcionais. | | `verify()` | Abre a caixa de diálogo do CAPTCHA. O resultado chega pelo listener. | | `refresh()` / `cancel()` / `dismiss()` | Recarrega o desafio atual / interrompe o fluxo e fecha a caixa de diálogo / fecha a caixa de diálogo. | | `CaptchalaClient.destroy()` | Libera o singleton. | | `CaptchalaResult` | `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. Envie `passToken` ao seu backend. `ttl` está obsoleto desde a 1.2.0: o servidor define a validade do token e pode alterá-la; use `onExpired`. | | `CaptchalaError` | `code`, `message`, `detail`. Passado para `onFail` (o usuário pode tentar de novo) e `onError` (erro de rede, configuração ou sistema). | ```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 ``` ### Configuração {#configuration} | Setter | Padrão | Significado | | --- | --- | --- | | `setAppKey(string)` | obrigatório | A App Key do painel. | | `setAction(string)` | `default` | Ação de negócio (`login`, `register`, `pay`, …). Deve ser igual à action do `server_token`. | | `setLang(string)` | `''` (auto) | Idioma do desafio, por exemplo `en`, `zh-CN`. | | `setTheme(string)` | `auto` | `auto` (segue o sistema), `light` ou `dark`. | | `setServerToken(string \| null)` | `null` | O `server_token` emitido pelo seu backend. | | `setOnServerTokenExpired(cb)` | `null` | `() => Promise` que busca um `server_token` novo no seu backend. | | `setTimeout(number)` | `10000` | Tempo limite das requisições, em ms. | | `setEnableVoice(boolean)` | `true` | Oferece o desafio em áudio. | | `setEnableOfflineMode(boolean)` | `false` | Permite o caminho alternativo em caso de indisponibilidade. Os resultados trazem `isOffline` / `isClientOnly`. | | `setMaskClosable(boolean)` | `false` | Tocar no fundo fecha a caixa de diálogo. | | `setCollectOdid(boolean)` | `true` | Envia um hash do ODID do aparelho (veja [Privacidade](#privacy)). | | `setLoadingStyle(string)` | `'spinner'` | Indicador de carregamento, veja [Indicador de carregamento](#loading-indicator). | | `setLoadingColor(string \| null)` | branco | Cor do indicador, `#RRGGBB` ou `#RRGGBBAA`. | | `setLoadingSize(string)` | `'medium'` | `'small'`, `'medium'` ou `'large'`. | | `setLoadingDelay(number)` | `300` | Milissegundos até o indicador aparecer, `0`–`5000`. | | `setDebug(boolean)` | `false` | Log detalhado durante o desenvolvimento. | ## Expiração do token {#token-expiry} O pass token recebido em `onSuccess` tem validade limitada, definida pelo servidor. Se a sua página não o usar até lá, o `onExpired(passToken)` do listener é chamado uma única vez, para que você descarte o token guardado e peça ao usuário que verifique de novo, em vez de enviar um token expirado. Inicie uma nova verificação com `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ão é chamado depois de um novo `verify()`, `init()` ou `destroy()`. Disponível a partir da 1.2.0. ## Indicador de carregamento {#loading-indicator} Enquanto o desafio carrega, o SDK mostra um pequeno indicador sobre o fundo escurecido. Ele só aparece quando o carregamento demora mais que `setLoadingDelay` (padrão 300 ms) e some quando o desafio é exibido. Disponível a partir da 1.2.0. - `setLoadingStyle`: `'spinner'` (padrão, raios), `'ring'` (um arco girando), `'dots'` ou `'none'`. Com `'none'` nada é exibido: mostre seu próprio indicador de `verify()` até `onReady`. - `setLoadingColor`: `#RRGGBB` ou `#RRGGBBAA`, padrão branco. - `setLoadingSize`: `'small'`, `'medium'` (padrão) ou `'large'`. - `setLoadingDelay`: milissegundos, `0`–`5000`. ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## Validação no servidor {#server-side-validation} Encaminhe `result.passToken` ao seu backend e valide-o na API da CaptchaLa. Nunca coloque `X-App-Secret` no app. ```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" } ``` Aceite a requisição apenas quando `data.valid` for `true` e `data.uid` for igual ao usuário para quem você emitiu o `server_token`. Os tokens são de uso único. Veja a resposta completa e os códigos de erro na [Referência da API](../api-reference). ## Privacidade {#privacy} O SDK lê um conjunto de atributos do aparelho que não exigem permissão (modelo, versão do sistema, tela, localidade, fuso horário e similares) e os usa somente para verificação e prevenção de fraude. Por padrão, também envia um hash SHA-256 truncado do ODID do aparelho, nunca o valor bruto. Não são coletados OAID, UDID, número de série nem dados de conta. Para desativar o hash do ODID: ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setCollectOdid(false) // the ODID is never read .build(); ``` Se mantiver ativado, declare um identificador de dispositivo usado para prevenção de fraude na sua política de privacidade e no rótulo de privacidade da AppGallery. ## Solução de problemas {#troubleshooting} - **`ohpm install` não encontra o pacote** O caminho `file:` é relativo ao módulo `entry`. Verifique se o arquivo está em `entry/libs/` e se o nome no `oh-package.json5` é exatamente o mesmo. - **A versão antiga continua em uso após a atualização** Apague o `.har` antigo de `entry/libs/`, atualize a versão no caminho `file:` e execute `ohpm install` (ou **Sync Now**) de novo. - **O SHA-256 não confere** Baixe o HAR novamente em [**Downloads de SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). Não publique um arquivo cujo checksum seja diferente do exibido no painel. - **`onError` com um código `server_token_*`** Verifique se o `setAction` do app é igual à `action` usada na emissão do token e se `setOnServerTokenExpired` retorna um token novo. - **O aparelho roda HarmonyOS 4.x ou anterior** Não é suportado. Esses aparelhos executam apps Android; use o [SDK Android](./android). ## Requisitos {#requirements} - HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) ou superior, modelo Stage - Tipos de dispositivo: celular, tablet, 2 em 1 - ABIs: `arm64-v8a`, `x86_64` (emulador) - `ohos.permission.INTERNET`