Skip to content

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.

  1. 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.
  2. Descarga el HAR de HarmonyOS, por ejemplo captchala-1.2.0.har.
  3. Compara su SHA-256 con el valor que muestra la página de descarga. Si no coinciden, no uses el archivo.
bash
# macOS / Linux
shasum -a 256 captchala-1.2.0.har

# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256
  1. Copia el archivo a entry/libs/ y añádelo a entry/oh-package.json5:
json5
// entry/oh-package.json5
{
  "dependencies": {
    "@captchala/captchala": "file:./libs/captchala-1.2.0.har"
  }
}
  1. Ejecuta ohpm install en el directorio entry, o pulsa Sync Now en DevEco Studio.
bash
cd entry
ohpm install

El 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:

json5
// 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:

  1. Tu backend emite un server_token de un solo uso para el usuario autenticado (consulta Server token).
  2. La app se lo pasa al SDK y abre el CAPTCHA.
  3. onSuccess devuelve un passToken; la app lo envía a tu backend.
  4. Tu backend valida el passToken (consulta Validación en el 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 ​

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:

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
  }
}

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ímboloPropósito
CaptchalaClient.getClient(uiContext)Punto de entrada singleton, vinculado al UIContext de tu página.
CaptchalaConfigBuilderBuilder 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.
CaptchalaResultpassToken, 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.
CaptchalaErrorcode, message, detail. Se pasa a onFail (el usuario puede reintentar) y a onError (error de red, configuración o 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

Configuración ​

SetterValor por defectoSignificado
setAppKey(string)obligatorioTu App Key del panel.
setAction(string)defaultAcció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)autoauto (sigue al sistema), light o dark.
setServerToken(string | null)nullEl server_token emitido por tu backend.
setOnServerTokenExpired(cb)null() => Promise<string | null> que obtiene un server_token nuevo de tu backend.
setTimeout(number)10000Tiempo de espera de las solicitudes, en ms.
setEnableVoice(boolean)trueOfrece el desafío de audio.
setEnableOfflineMode(boolean)falsePermite la ruta alternativa ante caídas. Sus resultados llevan isOffline / isClientOnly.
setMaskClosable(boolean)falseTocar el fondo cierra el diálogo.
setCollectOdid(boolean)trueEnvía un hash del ODID del dispositivo (consulta Privacidad).
setLoadingStyle(string)'spinner'Indicador de carga, consulta Indicador de carga.
setLoadingColor(string | null)blancoColor del indicador, #RRGGBB o #RRGGBBAA.
setLoadingSize(string)'medium''small', 'medium' o 'large'.
setLoadingDelay(number)300Milisegundos antes de que aparezca el indicador, 0–5000.
setDebug(boolean)falseRegistro 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().

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 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 desde verify() hasta onReady.
  • setLoadingColor: #RRGGBB o #RRGGBBAA, blanco por defecto.
  • setLoadingSize: 'small', 'medium' (por defecto) o 'large'.
  • setLoadingDelay: milisegundos, 0–5000.
ts
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.

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" }

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:

ts
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 install no encuentra el paquete
    La ruta file: es relativa al módulo entry. Comprueba que el archivo está en entry/libs/ y que su nombre coincide exactamente con el de oh-package.json5.

  • Tras actualizar se sigue usando la versión anterior
    Elimina el .har antiguo de entry/libs/, actualiza la versión en la ruta file: y vuelve a ejecutar ohpm 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.

  • onError con un código server_token_*
    Comprueba que el setAction de la app coincide con la action usada al emitir el token y que setOnServerTokenExpired devuelve 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

MIT-licensed examples · CaptchaLa is operated independently