Electron SDK

Electron SDK работает полностью в главном процессе, открывая нативное, управляемое ОС окно CAPTCHA. Renderer никогда не касается проверки — оставьте это так из соображений безопасности.

Демо на GitHub

📦

Captcha-La/electron-demo — полный рабочий пример со всеми шагами интеграции.

Установка

npm install @captchala/electron

Пакет рассчитан на Electron 28+ (демо закрепляет ^33.0.0) и Node 18+. Запустите демо целиком командой:

npm install
npm start

Быстрый старт

// main.js (Electron main process — never the renderer)
const { app, BrowserWindow, ipcMain } = require('electron');
const path = require('path');
const { CaptchalaClient } = require('@captchala/electron');

let currentClient = null;

ipcMain.handle('verify', async (event, opts) => {
  // 1. Fetch a one-shot server_token from YOUR backend.
  const serverToken = await fetchServerTokenFromYourBackend(opts.action);

  // 2. Tear down any prior client, then build a fresh one.
  if (currentClient) { currentClient.destroy(); currentClient = null; }
  currentClient = new CaptchalaClient({
    appKey: 'YOUR_APP_KEY',
    serverToken,
    action: opts.action,        // 'login' | 'register' | 'pay' | …
    lang:   opts.lang,          // 'en' | 'zh-CN' | 'ja' | …
    theme:  opts.theme,         // 'light' | 'dark'
    timeoutMs: 15000,
    retryCount: 3,
    onReady: () => event.sender.send('captcha-status', 'ready'),
    onFail:  (e) => event.sender.send('captcha-status', `recoverable: ${e.code}`),
  });

  try {
    const result = await currentClient.verify();
    // Send result.passToken to YOUR backend for validation.
    return { success: true, passToken: result.passToken };
  } catch (err) {
    return { success: false, error: err.message };
  } finally {
    if (currentClient) { currentClient.destroy(); currentClient = null; }
  }
});

function createWindow() {
  const win = new BrowserWindow({
    width: 520, height: 640, resizable: false,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false,
    },
  });
  win.loadFile('index.html');
}

app.whenReady().then(createWindow);
app.on('window-all-closed', () => app.quit());

// preload.js — bridge the renderer to the main-process verify().
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('captchala', {
  verify:   (opts)     => ipcRenderer.invoke('verify', opts),
  onStatus: (callback) => ipcRenderer.on('captcha-status', (_, msg) => callback(msg)),
});

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

Символ	Назначение
new CaptchalaClient({...})	Создаёт одноразовый клиент. Передайте appKey, serverToken, action, lang, theme, timeoutMs, retryCount плюс обработчики событий.
await client.verify()	Открывает нативное окно CAPTCHA. Разрешается результатом при успехе, отклоняется при жёсткой ошибке.
onReady / onFail	Опциональные обработчики, передаваемые в конструктор. onFail — для восстанавливаемых сбоев (SDK повторит попытку).
result.passToken	Token для проверки на вашем backend. Всегда непрозрачен для клиента.
client.destroy()	Закрывает окно и освобождает ресурсы. Всегда вызывайте, как только закончили работу с экземпляром клиента.
CaptchalaClient.version()	Статический helper, возвращающий строку версии SDK. Полезно в overlay-ях поддержки / отладки.

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

Перешлите result.passToken (или result.token) на ваш backend и проверьте его через API CaptchaLa. Никогда не размещайте X-App-Secret в клиентском коде.

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<result.passToken>", "client_ip": "<end-user IP>" }

См. Справочник API для полного endpoint проверки и потока X-App-Key / X-App-Secret.

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

• Не импортируйте SDK в renderer
  @captchala/electron предназначен только для main-процесса. Передавайте его результат через contextBridge + ipcRenderer.invoke(), как это делает preload.js в демо. Сохраняйте nodeIntegration: false и contextIsolation: true.

• Модуль не найден в runtime
  @captchala/electron — это обычная зависимость, а не devDependency — он должен быть упакован в финальное приложение. Сборщики вроде electron-builder включают его автоматически.

• Окно открывается за основным окном
  Это особенность Linux/X11. Передайте parent в собственное BrowserWindow, если оборачиваете окно CAPTCHA, или вызовите mainWindow.focus() после возврата из verify().

• Требуется Electron 28+
  Демо объявляет electron: ^33.0.0. Более старый Electron может не иметь API, на которые опирается SDK; зафиксируйте 28+ и Node 18+.

Требования

• Electron 28+ (в демо используется 33.x)
• Node 18+
• Кросс-платформенность: macOS, Windows 10 1809+, Linux (X11 / Wayland)