Skip to content

HarmonyOS SDK ​

SDK 1.2.0

Обновлено для 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.

Установка ​

SDK не публикуется в ohpm. Скачайте HAR из панели управления и подключите его как локальную зависимость.

  1. Войдите в панель управления и откройте Загрузка SDK. На той же странице есть демо-проект для 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
  1. Скопируйте файл в entry/libs/ и добавьте его в entry/oh-package.json5:
json5
// entry/oh-package.json5
{
  "dependencies": {
    "@captchala/captchala": "file:./libs/captchala-1.2.0.har"
  }
}
  1. Выполните 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).
  2. Приложение передаёт его в SDK и открывает CAPTCHA.
  3. onSuccess возвращает passToken; приложение отправляет его на ваш бэкенд.
  4. Ваш бэкенд проверяет passToken (см. Серверная проверка).
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 ​

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; также можно использовать серверный SDK для PHP / Go.

Поверхность API ​

СимволНазначение
CaptchalaClient.getClient(uiContext)Точка входа (singleton), привязанная к UIContext вашей страницы.
CaptchalaConfigBuilderFluent-билдер конфигурации (см. таблицу ниже). build() возвращает CaptchalaConfig.
init(config)Применяет конфигурацию. Возвращает клиент, поэтому вызовы можно объединять в цепочку.
setListener(listener)Регистрирует CaptchalaListener. Обязателен только onSuccess; onReady, onFail, onError, onClose и onExpired (см. Истечение токена) необязательны.
verify()Открывает диалог CAPTCHA. Результат приходит через listener.
refresh() / cancel() / dismiss()Перезагрузить текущее задание / прервать процесс и закрыть диалог / закрыть диалог.
CaptchalaClient.destroy()Освобождает singleton.
CaptchalaResultpassToken, challengeId, ttl, isOffline, isClientOnly. Отправьте passToken на ваш бэкенд. Поле ttl устарело начиная с 1.2.0: срок жизни токена определяет сервер, и он может меняться; используйте onExpired.
CaptchalaErrorcode, 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

Конфигурация ​

МетодПо умолчаниюОписание
setAppKey(string)обязательноВаш App Key из панели управления.
setAction(string)defaultБизнес-действие (login, register, pay, …). Должно совпадать с action у server_token.
setLang(string)'' (auto)Язык задания, например en, zh-CN.
setTheme(string)autoauto (следует системной теме), light или dark.
setServerToken(string | null)nullserver_token, выпущенный вашим бэкендом.
setOnServerTokenExpired(cb)null() => Promise<string | null>, получающий новый server_token с вашего бэкенда.
setTimeout(number)10000Таймаут запроса, мс.
setEnableVoice(boolean)trueПредлагать аудиозадание.
setEnableOfflineMode(boolean)falseРазрешить резервный путь при сбое. Результаты помечаются isOffline / isClientOnly.
setMaskClosable(boolean)falseНажатие на фон закрывает диалог.
setCollectOdid(boolean)trueПередавать хеш ODID устройства (см. Конфиденциальность).
setLoadingStyle(string)'spinner'Индикатор загрузки, см. Индикатор загрузки.
setLoadingColor(string | null)белыйЦвет индикатора, #RRGGBB или #RRGGBBAA.
setLoadingSize(string)'medium''small', 'medium' или 'large'.
setLoadingDelay(number)300Задержка в миллисекундах перед появлением индикатора, 0–5000.
setDebug(boolean)falseПодробное логирование во время разработки.

Истечение токена ​

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.

Индикатор загрузки ​

Пока загружается проверка, 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();

Серверная проверка ​

Передайте 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": "<result.passToken>", "expected_action": "login" }

Принимайте запрос, только если data.valid равно true, а data.uid совпадает с пользователем, для которого вы выпустили server_token. Токены одноразовые. Полный ответ и коды ошибок описаны в справочнике API.

Конфиденциальность ​

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 идентификатор устройства, используемый для защиты от мошенничества.

Устранение неполадок ​

  • ohpm install не находит пакет
    Путь file: указывается относительно модуля entry. Проверьте, что файл лежит в entry/libs/, а его имя точно совпадает с указанным в oh-package.json5.

  • После обновления используется старая версия
    Удалите старый .har из entry/libs/, обновите версию в пути file: и снова выполните ohpm install (или Sync Now).

  • SHA-256 не совпадает
    Скачайте HAR заново в разделе Загрузка SDK. Не выпускайте файл, контрольная сумма которого отличается от указанной в панели.

  • onError с кодом server_token_*
    Проверьте, что setAction в приложении совпадает с action, указанным при выпуске токена, и что setOnServerTokenExpired возвращает новый токен.

  • Устройство работает на HarmonyOS 4.x или старше
    Не поддерживается. Такие устройства запускают Android-приложения; используйте Android SDK.

Требования ​

  • HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) и новее, модель Stage
  • Типы устройств: телефон, планшет, 2-в-1
  • ABI: arm64-v8a, x86_64 (эмулятор)
  • ohos.permission.INTERNET

MIT-licensed examples · CaptchaLa is operated independently