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.
- 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.
- Baixe o HAR do HarmonyOS, por exemplo
captchala-1.2.0.har. - Compare o SHA-256 do arquivo com o valor exibido na página de download. Se forem diferentes, não use o arquivo.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- Copie o arquivo para
entry/libs/e adicione-o aoentry/oh-package.json5:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}- Execute
ohpm installno diretórioentryou clique em Sync Now no DevEco Studio.
cd entry
ohpm installO 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:
// 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:
- O seu backend emite um
server_tokende uso único para o usuário conectado (veja Server token). - O app repassa o token ao SDK e abre o CAPTCHA.
onSuccessretorna umpassToken; o app o envia ao seu backend.- O seu backend valida o
passToken(veja Validação no servidor).
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:
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
}
}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í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) 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). |
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 singletonConfiguração
| 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<string | null> 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). |
setLoadingStyle(string) | 'spinner' | Indicador de carregamento, veja Indicador de carregamento. |
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
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().
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 deverify()atéonReady.setLoadingColor:#RRGGBBou#RRGGBBAA, padrão branco.setLoadingSize:'small','medium'(padrão) ou'large'.setLoadingDelay: milissegundos,0–5000.
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.
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:
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 installnão encontra o pacote
O caminhofile:é relativo ao móduloentry. Verifique se o arquivo está ementry/libs/e se o nome nooh-package.json5é exatamente o mesmo.A versão antiga continua em uso após a atualização
Apague o.harantigo deentry/libs/, atualize a versão no caminhofile:e executeohpm 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.onErrorcom um códigoserver_token_*
Verifique se osetActiondo app é igual àactionusada na emissão do token e sesetOnServerTokenExpiredretorna 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