SDK de HarmonyOS
SDK 1.2.0
Actualizado para el SDK 1.2.0. Algunos detalles solo están disponibles en inglés: consulte la página en inglés y el registro de cambios.
SDK en ArkTS para HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 o posterior), distribuido como un único .har (@captchala/captchala). Versión actual: 1.2.0. Ofrece el mismo flujo de verificación que los SDK de Android e iOS: el desafío se abre en un diálogo sobre tu página y tu backend valida el passToken que devuelve.
INFO
HarmonyOS 4.x y versiones anteriores ejecutan apps de Android. En esos dispositivos usa el SDK de Android.
Instalación
El SDK no está publicado en ohpm. Descarga el HAR desde el panel y añádelo como dependencia local.
- Inicia sesión en el panel y abre Descargas de SDK. La misma página ofrece también un proyecto de demostración de HarmonyOS (código fuente) que puedes abrir en DevEco Studio.
- Descarga el HAR de HarmonyOS, por ejemplo
captchala-1.2.0.har. - Compara su SHA-256 con el valor que muestra la página de descarga. Si no coinciden, no uses el archivo.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- Copia el archivo a
entry/libs/y añádelo aentry/oh-package.json5:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}- Ejecuta
ohpm installen el directorioentry, o pulsa Sync Now en DevEco Studio.
cd entry
ohpm installEl HAR es una compilación de release ofuscada que solo expone la API pública descrita abajo. Las reglas de ofuscación para el consumidor van dentro del HAR, así que tu compilación de release no necesita reglas keep adicionales.
Permisos
El SDK usa un único permiso, ohos.permission.INTERNET. Nunca solicita ni muestra avisos de permisos en tiempo de ejecución. Asegúrate de que tu módulo entry lo declara:
// entry/src/main/module.json5
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" }
]
}
}Actualización
Descarga el nuevo HAR, cópialo a entry/libs/, cambia la versión en la ruta file: de entry/oh-package.json5, elimina el .har anterior y vuelve a ejecutar ohpm install.
Inicio rápido
El flujo:
- Tu backend emite un
server_tokende un solo uso para el usuario autenticado (consulta Server token). - La app se lo pasa al SDK y abre el CAPTCHA.
onSuccessdevuelve unpassToken; la app lo envía a tu backend.- Tu backend valida el
passToken(consulta Validación en el 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
El server_token lo genera tu backend, no la app, llamando a /v1/server/challenge/issue con tu X-App-Key + X-App-Secret. Envía bind_uid con tu propio ID de usuario para que el token, y el passToken que se obtiene a partir de él, pertenezcan a ese usuario:
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
}
}Devuelve data.server_token (prefijo sct_) a la app. action debe coincidir con el valor pasado a setAction. Con setOnServerTokenExpired, el SDK obtiene un token nuevo y reintenta por su cuenta cuando un token se rechaza durante el desafío; devuelve null para recibir el error original.
Las opciones de vinculación de identidad (bind_uid, bind_ip) se definen solo en tu servidor al emitir el token. La app nunca las envía. Consulta todos los parámetros en la Referencia de la API o usa el SDK de servidor de PHP / Go.
Superficie de la API
| Símbolo | Propósito |
|---|---|
CaptchalaClient.getClient(uiContext) | Punto de entrada singleton, vinculado al UIContext de tu página. |
CaptchalaConfigBuilder | Builder fluido para la configuración (ver tabla más abajo). build() devuelve un CaptchalaConfig. |
init(config) | Aplica la configuración. Devuelve el cliente, por lo que las llamadas se pueden encadenar. |
setListener(listener) | Registra un CaptchalaListener. Solo onSuccess es obligatorio; onReady, onFail, onError, onClose y onExpired (consulta Caducidad del token) son opcionales. |
verify() | Abre el diálogo del CAPTCHA. El resultado llega a través del listener. |
refresh() / cancel() / dismiss() | Recarga el desafío actual / detiene el flujo y cierra el diálogo / cierra el diálogo. |
CaptchalaClient.destroy() | Libera el singleton. |
CaptchalaResult | passToken, challengeId, ttl, isOffline, isClientOnly. Envía passToken a tu backend. ttl está obsoleto desde 1.2.0: el servidor decide la vida útil del token y puede cambiarla; usa onExpired. |
CaptchalaError | code, message, detail. Se pasa a onFail (el usuario puede reintentar) y a onError (error de red, configuración o 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 singletonConfiguración
| Setter | Valor por defecto | Significado |
|---|---|---|
setAppKey(string) | obligatorio | Tu App Key del panel. |
setAction(string) | default | Acción de negocio (login, register, pay, …). Debe coincidir con la action del server_token. |
setLang(string) | '' (auto) | Idioma del desafío, p. ej. en, zh-CN. |
setTheme(string) | auto | auto (sigue al sistema), light o dark. |
setServerToken(string | null) | null | El server_token emitido por tu backend. |
setOnServerTokenExpired(cb) | null | () => Promise<string | null> que obtiene un server_token nuevo de tu backend. |
setTimeout(number) | 10000 | Tiempo de espera de las solicitudes, en ms. |
setEnableVoice(boolean) | true | Ofrece el desafío de audio. |
setEnableOfflineMode(boolean) | false | Permite la ruta alternativa ante caídas. Sus resultados llevan isOffline / isClientOnly. |
setMaskClosable(boolean) | false | Tocar el fondo cierra el diálogo. |
setCollectOdid(boolean) | true | Envía un hash del ODID del dispositivo (consulta Privacidad). |
setLoadingStyle(string) | 'spinner' | Indicador de carga, consulta Indicador de carga. |
setLoadingColor(string | null) | blanco | Color del indicador, #RRGGBB o #RRGGBBAA. |
setLoadingSize(string) | 'medium' | 'small', 'medium' o 'large'. |
setLoadingDelay(number) | 300 | Milisegundos antes de que aparezca el indicador, 0–5000. |
setDebug(boolean) | false | Registro detallado durante el desarrollo. |
Caducidad del token
El pass token de onSuccess es válido durante un tiempo limitado que decide el servidor. Si tu página no lo ha usado para entonces, se llama una vez a onExpired(passToken) del listener, para que puedas borrar el token guardado y pedir al usuario que vuelva a verificar en lugar de enviar un token caducado. Inicia una nueva verificación con 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 no se llama después de un nuevo verify(), init() o destroy(). Disponible desde 1.2.0.
Indicador de carga
Mientras se carga el desafío, el SDK muestra un pequeño indicador sobre la capa de oscurecimiento. Solo aparece si la carga tarda más que setLoadingDelay (300 ms por defecto) y desaparece cuando se muestra el desafío. Disponible desde 1.2.0.
setLoadingStyle:'spinner'(por defecto, radios),'ring'(un arco que gira),'dots'o'none'. Con'none'no se muestra nada: muestra tu propio indicador desdeverify()hastaonReady.setLoadingColor:#RRGGBBo#RRGGBBAA, blanco por defecto.setLoadingSize:'small','medium'(por defecto) o'large'.setLoadingDelay: milisegundos,0–5000.
const config = new CaptchalaConfigBuilder()
.setAppKey('YOUR_APP_KEY')
.setLoadingStyle('dots')
.setLoadingColor('#3B82F6')
.setLoadingSize('small')
.setLoadingDelay(500)
.build();Validación en el servidor
Reenvía result.passToken a tu backend y valídalo con la API de CaptchaLa. Nunca incluyas X-App-Secret en la 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" }Acepta la solicitud solo cuando data.valid sea true y data.uid coincida con el usuario para el que emitiste el server_token. Los tokens son de un solo uso. Consulta la respuesta completa y los códigos de error en la Referencia de la API.
Privacidad
El SDK lee un conjunto de atributos del dispositivo que no requieren permisos (modelo, versión del sistema, pantalla, configuración regional, zona horaria y similares) y los usa solo para la verificación y la prevención del fraude. Por defecto también envía un hash SHA-256 truncado del ODID del dispositivo, nunca el valor original. No se recopilan OAID, UDID, número de serie ni datos de cuenta. Para desactivar el hash del ODID:
const config = new CaptchalaConfigBuilder()
.setAppKey('YOUR_APP_KEY')
.setCollectOdid(false) // the ODID is never read
.build();Si lo mantienes activado, declara un identificador de dispositivo usado para prevenir el fraude en tu política de privacidad y en la etiqueta de privacidad de AppGallery.
Solución de problemas
ohpm installno encuentra el paquete
La rutafile:es relativa al móduloentry. Comprueba que el archivo está enentry/libs/y que su nombre coincide exactamente con el deoh-package.json5.Tras actualizar se sigue usando la versión anterior
Elimina el.harantiguo deentry/libs/, actualiza la versión en la rutafile:y vuelve a ejecutarohpm install(o Sync Now).El SHA-256 no coincide
Descarga de nuevo el HAR desde Descargas de SDK. No publiques un archivo cuya suma de comprobación no coincida con la del panel.onErrorcon un códigoserver_token_*
Comprueba que elsetActionde la app coincide con laactionusada al emitir el token y quesetOnServerTokenExpireddevuelve un token nuevo.El dispositivo usa HarmonyOS 4.x o anterior
No es compatible. Esos dispositivos ejecutan apps de Android; usa el SDK de Android.
Requisitos
- HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) o posterior, modelo Stage
- Tipos de dispositivo: teléfono, tableta, 2 en 1
- ABI:
arm64-v8a,x86_64(emulador) ohos.permission.INTERNET