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 из панели управления и подключите его как локальную зависимость.
- Войдите в панель управления и откройте Загрузка SDK. На той же странице есть демо-проект для HarmonyOS (исходники), который можно открыть в DevEco Studio.
- Скачайте HAR для HarmonyOS, например
captchala-1.2.0.har. - Сравните SHA-256 файла со значением на странице загрузки. Если они не совпадают, не используйте файл.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- Скопируйте файл в
entry/libs/и добавьте его вentry/oh-package.json5:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}- Выполните
ohpm installв каталогеentryили нажмите Sync Now в DevEco Studio.
cd entry
ohpm installHAR — обфусцированная release-сборка, которая открывает только описанный ниже публичный API. Правила обфускации для потребителя уже включены в HAR, поэтому дополнительные keep-правила в вашей release-сборке не нужны.
Разрешения
SDK использует одно разрешение — ohos.permission.INTERNET. Он никогда не запрашивает разрешения во время выполнения и не показывает диалоги. Убедитесь, что ваш модуль entry его объявляет:
// entry/src/main/module.json5
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" }
]
}
}Обновление
Скачайте новый HAR, скопируйте его в entry/libs/, измените версию в пути file: в entry/oh-package.json5, удалите старый .har и снова выполните ohpm install.
Быстрый старт
Порядок работы:
- Ваш бэкенд выпускает одноразовый
server_tokenдля вошедшего пользователя (см. Server token). - Приложение передаёт его в SDK и открывает CAPTCHA.
onSuccessвозвращаетpassToken; приложение отправляет его на ваш бэкенд.- Ваш бэкенд проверяет
passToken(см. Серверная проверка).
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 принадлежали этому пользователю:
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
}
}Верните data.server_token (префикс sct_) в приложение. action должен совпадать со значением, переданным в setAction. Если задан setOnServerTokenExpired, SDK сам получает новый токен и повторяет попытку, когда токен отклонён во время задания; верните null, чтобы получить исходную ошибку.
Параметры привязки к личности (bind_uid, bind_ip) задаются только на вашем сервере при выпуске токена. Приложение их никогда не отправляет. Все параметры описаны в справочнике API; также можно использовать серверный SDK для PHP / Go.
Поверхность API
| Символ | Назначение |
|---|---|
CaptchalaClient.getClient(uiContext) | Точка входа (singleton), привязанная к UIContext вашей страницы. |
CaptchalaConfigBuilder | Fluent-билдер конфигурации (см. таблицу ниже). build() возвращает CaptchalaConfig. |
init(config) | Применяет конфигурацию. Возвращает клиент, поэтому вызовы можно объединять в цепочку. |
setListener(listener) | Регистрирует CaptchalaListener. Обязателен только onSuccess; onReady, onFail, onError, onClose и onExpired (см. Истечение токена) необязательны. |
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 (ошибка сети, конфигурации или системы). |
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) | auto | auto (следует системной теме), light или dark. |
setServerToken(string | null) | null | server_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().
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.
const config = new CaptchalaConfigBuilder()
.setAppKey('YOUR_APP_KEY')
.setLoadingStyle('dots')
.setLoadingColor('#3B82F6')
.setLoadingSize('small')
.setLoadingDelay(500)
.build();Серверная проверка
Передайте result.passToken на ваш бэкенд и проверьте его через API CaptchaLa. Никогда не помещайте X-App-Secret в приложение.
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:
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