--- title: SDK de HarmonyOS description: "SDK de CaptchaLa para HarmonyOS NEXT (ArkTS): instalación del HAR desde el panel, flujo de verificación y validación en el servidor." --- # SDK de HarmonyOS ::: info 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](/sdk/harmony) y el [registro de cambios](/changelog#sdk-1-2-0). ::: 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](./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**](https://dash.captcha.la/sdk-downloads?platform=harmony). 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 ``` 4. 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" } } ``` 5. 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](#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](#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} 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](../api-reference#server-token) o usa el SDK de servidor de [PHP](./server-php) / [Go](./server-go). ## Superficie de la API {#api-surface} | 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](#token-expiry)) 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). | ```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 {#configuration} | 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` 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](#privacy)). | | `setLoadingStyle(string)` | `'spinner'` | Indicador de carga, consulta [Indicador de carga](#loading-indicator). | | `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 {#token-expiry} 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 {#loading-indicator} 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 {#server-side-validation} 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": "", "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](../api-reference). ## Privacidad {#privacy} 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 {#troubleshooting} - **`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**](https://dash.captcha.la/sdk-downloads?platform=harmony). 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](./android). ## Requisitos {#requirements} - 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`