--- title: HarmonyOS SDK description: "SDK CaptchaLa для HarmonyOS NEXT (ArkTS): установка HAR из панели управления, процесс проверки и серверная валидация." --- # HarmonyOS SDK ::: info SDK 1.2.0 Обновлено для SDK 1.2.0. Некоторые подробности доступны только на английском: см. [английскую версию](/sdk/harmony) и [журнал изменений](/changelog#sdk-1-2-0). ::: ArkTS SDK для **HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 и новее)**, поставляется одним файлом `.har` (`@captchala/captchala`). Текущая версия: **1.2.0**. Процесс проверки такой же, как в SDK для Android и iOS: задание открывается в диалоге поверх вашей страницы, а ваш бэкенд проверяет возвращённый `passToken`. ::: info HarmonyOS 4.x и более ранние версии запускают Android-приложения. На таких устройствах используйте [Android SDK](./android). ::: ## Установка SDK **не публикуется в ohpm**. Скачайте HAR из панели управления и подключите его как локальную зависимость. 1. Войдите в панель управления и откройте [**Загрузка SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). На той же странице есть демо-проект для HarmonyOS (исходники), который можно открыть в DevEco Studio. 2. Скачайте HAR для HarmonyOS, например `captchala-1.2.0.har`. 3. Сравните SHA-256 файла со значением на странице загрузки. Если они не совпадают, не используйте файл. ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. Скопируйте файл в `entry/libs/` и добавьте его в `entry/oh-package.json5`: ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. Выполните `ohpm install` в каталоге `entry` или нажмите **Sync Now** в DevEco Studio. ```bash cd entry ohpm install ``` HAR — обфусцированная release-сборка, которая открывает только описанный ниже публичный API. Правила обфускации для потребителя уже включены в HAR, поэтому дополнительные keep-правила в вашей release-сборке не нужны. ### Разрешения SDK использует одно разрешение — `ohos.permission.INTERNET`. Он никогда не запрашивает разрешения во время выполнения и не показывает диалоги. Убедитесь, что ваш модуль entry его объявляет: ```json5 // entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } } ``` ### Обновление Скачайте новый HAR, скопируйте его в `entry/libs/`, измените версию в пути `file:` в `entry/oh-package.json5`, удалите старый `.har` и снова выполните `ohpm install`. ## Быстрый старт Порядок работы: 1. Ваш бэкенд выпускает одноразовый `server_token` для вошедшего пользователя (см. [Server token](#server-token)). 2. Приложение передаёт его в SDK и открывает CAPTCHA. 3. `onSuccess` возвращает `passToken`; приложение отправляет его на ваш бэкенд. 4. Ваш бэкенд проверяет `passToken` (см. [Серверная проверка](#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} `server_token` выпускает ваш бэкенд, а не приложение: он вызывает `/v1/server/challenge/issue` с вашими `X-App-Key` + `X-App-Secret`. Передайте `bind_uid` с ID пользователя в вашей системе, чтобы токен и полученный из него `passToken` принадлежали этому пользователю: ```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 } } ``` Верните `data.server_token` (префикс `sct_`) в приложение. `action` должен совпадать со значением, переданным в `setAction`. Если задан `setOnServerTokenExpired`, SDK сам получает новый токен и повторяет попытку, когда токен отклонён во время задания; верните `null`, чтобы получить исходную ошибку. Параметры привязки к личности (`bind_uid`, `bind_ip`) задаются только на вашем сервере при выпуске токена. Приложение их никогда не отправляет. Все параметры описаны в [справочнике API](../api-reference#server-token); также можно использовать серверный SDK для [PHP](./server-php) / [Go](./server-go). ## Поверхность API {#api-surface} | Символ | Назначение | | --- | --- | | `CaptchalaClient.getClient(uiContext)` | Точка входа (singleton), привязанная к `UIContext` вашей страницы. | | `CaptchalaConfigBuilder` | Fluent-билдер конфигурации (см. таблицу ниже). `build()` возвращает `CaptchalaConfig`. | | `init(config)` | Применяет конфигурацию. Возвращает клиент, поэтому вызовы можно объединять в цепочку. | | `setListener(listener)` | Регистрирует `CaptchalaListener`. Обязателен только `onSuccess`; `onReady`, `onFail`, `onError`, `onClose` и `onExpired` (см. [Истечение токена](#token-expiry)) необязательны. | | `verify()` | Открывает диалог CAPTCHA. Результат приходит через listener. | | `refresh()` / `cancel()` / `dismiss()` | Перезагрузить текущее задание / прервать процесс и закрыть диалог / закрыть диалог. | | `CaptchalaClient.destroy()` | Освобождает singleton. | | `CaptchalaResult` | `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. Отправьте `passToken` на ваш бэкенд. Поле `ttl` устарело начиная с 1.2.0: срок жизни токена определяет сервер, и он может меняться; используйте `onExpired`. | | `CaptchalaError` | `code`, `message`, `detail`. Передаётся в `onFail` (пользователь может повторить) и `onError` (ошибка сети, конфигурации или системы). | ```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 ``` ### Конфигурация {#configuration} | Метод | По умолчанию | Описание | | --- | --- | --- | | `setAppKey(string)` | обязательно | Ваш App Key из панели управления. | | `setAction(string)` | `default` | Бизнес-действие (`login`, `register`, `pay`, …). Должно совпадать с action у `server_token`. | | `setLang(string)` | `''` (auto) | Язык задания, например `en`, `zh-CN`. | | `setTheme(string)` | `auto` | `auto` (следует системной теме), `light` или `dark`. | | `setServerToken(string \| null)` | `null` | `server_token`, выпущенный вашим бэкендом. | | `setOnServerTokenExpired(cb)` | `null` | `() => Promise`, получающий новый `server_token` с вашего бэкенда. | | `setTimeout(number)` | `10000` | Таймаут запроса, мс. | | `setEnableVoice(boolean)` | `true` | Предлагать аудиозадание. | | `setEnableOfflineMode(boolean)` | `false` | Разрешить резервный путь при сбое. Результаты помечаются `isOffline` / `isClientOnly`. | | `setMaskClosable(boolean)` | `false` | Нажатие на фон закрывает диалог. | | `setCollectOdid(boolean)` | `true` | Передавать хеш ODID устройства (см. [Конфиденциальность](#privacy)). | | `setLoadingStyle(string)` | `'spinner'` | Индикатор загрузки, см. [Индикатор загрузки](#loading-indicator). | | `setLoadingColor(string \| null)` | белый | Цвет индикатора, `#RRGGBB` или `#RRGGBBAA`. | | `setLoadingSize(string)` | `'medium'` | `'small'`, `'medium'` или `'large'`. | | `setLoadingDelay(number)` | `300` | Задержка в миллисекундах перед появлением индикатора, `0`–`5000`. | | `setDebug(boolean)` | `false` | Подробное логирование во время разработки. | ## Истечение токена {#token-expiry} Pass token из `onSuccess` действует ограниченное время, которое определяет сервер. Если страница не использовала его за это время, один раз вызывается `onExpired(passToken)` listener-а: очистите сохранённый токен и попросите пользователя пройти проверку снова, вместо того чтобы отправлять просроченный токен. Новую проверку запускает `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` не вызывается после нового `verify()`, `init()` или `destroy()`. Доступно с версии 1.2.0. ## Индикатор загрузки {#loading-indicator} Пока загружается проверка, SDK показывает небольшой индикатор поверх затемнения. Он появляется, только если загрузка длится дольше `setLoadingDelay` (по умолчанию 300 мс), и исчезает, когда проверка показана. Доступно с версии 1.2.0. - `setLoadingStyle`: `'spinner'` (по умолчанию, лучи), `'ring'` (вращающаяся дуга), `'dots'` или `'none'`. При `'none'` ничего не показывается: показывайте собственный индикатор от `verify()` до `onReady`. - `setLoadingColor`: `#RRGGBB` или `#RRGGBBAA`, по умолчанию белый. - `setLoadingSize`: `'small'`, `'medium'` (по умолчанию) или `'large'`. - `setLoadingDelay`: миллисекунды, `0`–`5000`. ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## Серверная проверка {#server-side-validation} Передайте `result.passToken` на ваш бэкенд и проверьте его через API CaptchaLa. Никогда не помещайте `X-App-Secret` в приложение. ```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" } ``` Принимайте запрос, только если `data.valid` равно `true`, а `data.uid` совпадает с пользователем, для которого вы выпустили `server_token`. Токены одноразовые. Полный ответ и коды ошибок описаны в [справочнике API](../api-reference). ## Конфиденциальность {#privacy} SDK считывает набор атрибутов устройства, не требующих разрешений (модель, версия ОС, экран, локаль, часовой пояс и т. п.), и использует их только для проверки и защиты от мошенничества. По умолчанию он также передаёт усечённый SHA-256-хеш ODID устройства, но никогда не исходное значение. OAID, UDID, серийный номер и данные аккаунта не собираются. Чтобы отключить хеш ODID: ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setCollectOdid(false) // the ODID is never read .build(); ``` Если оставляете его включённым, укажите в политике конфиденциальности и в метке конфиденциальности AppGallery идентификатор устройства, используемый для защиты от мошенничества. ## Устранение неполадок {#troubleshooting} - **`ohpm install` не находит пакет** Путь `file:` указывается относительно модуля `entry`. Проверьте, что файл лежит в `entry/libs/`, а его имя точно совпадает с указанным в `oh-package.json5`. - **После обновления используется старая версия** Удалите старый `.har` из `entry/libs/`, обновите версию в пути `file:` и снова выполните `ohpm install` (или **Sync Now**). - **SHA-256 не совпадает** Скачайте HAR заново в разделе [**Загрузка SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). Не выпускайте файл, контрольная сумма которого отличается от указанной в панели. - **`onError` с кодом `server_token_*`** Проверьте, что `setAction` в приложении совпадает с `action`, указанным при выпуске токена, и что `setOnServerTokenExpired` возвращает новый токен. - **Устройство работает на HarmonyOS 4.x или старше** Не поддерживается. Такие устройства запускают Android-приложения; используйте [Android SDK](./android). ## Требования {#requirements} - HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) и новее, модель Stage - Типы устройств: телефон, планшет, 2-в-1 - ABI: `arm64-v8a`, `x86_64` (эмулятор) - `ohos.permission.INTERNET`