Skip to content

SDK HarmonyOS ​

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 e o changelog.

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.

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

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 ou use o SDK de servidor PHP / Go.

Superfície da API ​

SímboloFinalidade
CaptchalaClient.getClient(uiContext)Ponto de entrada singleton, vinculado ao UIContext da sua página.
CaptchalaConfigBuilderBuilder 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) 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.
CaptchalaResultpassToken, 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.
CaptchalaErrorcode, 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 ​

SetterPadrãoSignificado
setAppKey(string)obrigatórioA App Key do painel.
setAction(string)defaultAçã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)autoauto (segue o sistema), light ou dark.
setServerToken(string | null)nullO server_token emitido pelo seu backend.
setOnServerTokenExpired(cb)null() => Promise<string | null> que busca um server_token novo no seu backend.
setTimeout(number)10000Tempo limite das requisições, em ms.
setEnableVoice(boolean)trueOferece o desafio em áudio.
setEnableOfflineMode(boolean)falsePermite o caminho alternativo em caso de indisponibilidade. Os resultados trazem isOffline / isClientOnly.
setMaskClosable(boolean)falseTocar no fundo fecha a caixa de diálogo.
setCollectOdid(boolean)trueEnvia um hash do ODID do aparelho (veja Privacidade).
setLoadingStyle(string)'spinner'Indicador de carregamento, veja Indicador de carregamento.
setLoadingColor(string | null)brancoCor do indicador, #RRGGBB ou #RRGGBBAA.
setLoadingSize(string)'medium''small', 'medium' ou 'large'.
setLoadingDelay(number)300Milissegundos até o indicador aparecer, 0–5000.
setDebug(boolean)falseLog detalhado durante o desenvolvimento.

Expiração do token ​

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 ​

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 ​

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

Privacidade ​

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 ​

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

Requisitos ​

  • 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

MIT-licensed examples · CaptchaLa is operated independently