Electron SDK

SDK Electron berjalan sepenuhnya dalam proses utama, membuka tetingkap CAPTCHA asli yang diuruskan OS. Proses penyumber (renderer) tidak terlibat dalam pengesahan — kekalkan pengasingan ini untuk keselamatan.

Demo di GitHub

📦

Captcha-La/electron-demo — contoh lengkap yang boleh dijalankan dengan semua langkah integrasi.

Pemasangan

npm install @captchala/electron

The package targets Electron 28+ (the demo pins ^33.0.0) and Node 18+. Run the demo end-to-end with:

npm install
npm start

Mula pantas

// 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 utama

Simbol	Tujuan
new CaptchalaClient({...})	Membina klien sekali pakai. Hantar appKey, serverToken, action, lang, theme, timeoutMs, retryCount serta pengendali peristiwa.
await client.verify()	Membuka tetingkap CAPTCHA asli. Resolve dengan keputusan jika berjaya, reject pada ralat berat.
onReady / onFail	Pengendali pilihan yang dihantar ke konstruktor. onFail adalah untuk kegagalan boleh pulih (SDK akan cuba semula).
result.passToken	Token untuk disahkan di backend anda. Sentiasa legap kepada klien.
client.destroy()	Menutup tetingkap dan membebaskan sumber. Sentiasa panggil selepas selesai menggunakan instance klien.
CaptchalaClient.version()	Pembantu statik yang mengembalikan rentetan versi SDK. Berguna dalam paparan sokongan / nyahpepijat.

Pengesahan di pelayan

Hantar result.passToken (atau result.token) ke backend anda dan sahkan menerusi API CaptchaLa. Jangan dedahkan X-App-Secret dalam kod klien.

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>" }

Lihat Rujukan API untuk endpoint pengesahan penuh dan aliran X-App-Key / X-App-Secret.

Penyelesaian masalah

• Jangan import SDK dalam renderer
  @captchala/electron hanya untuk proses utama. Dedahkan keputusannya melalui contextBridge + ipcRenderer.invoke() seperti preload.js demo. Kekalkan nodeIntegration: false dan contextIsolation: true.

• Modul tidak ditemui semasa runtime
  @captchala/electron adalah dependencies biasa, bukan devDependencies — mesti dibungkus dalam aplikasi akhir. electron-builder akan menyertakannya secara automatik.

• Tetingkap CAPTCHA muncul di belakang tetingkap utama
  Ini ciri Linux/X11. Hantar parent dalam BrowserWindow anda sendiri jika anda membungkus tetingkap CAPTCHA, atau panggil mainWindow.focus() selepas verify() kembali.

• Electron 28+ diperlukan
  Demo mengisytiharkan electron: ^33.0.0. Versi Electron lebih lama mungkin kekurangan API yang diperlukan oleh SDK; pin pada 28+ dan Node 18+.

Keperluan

• Electron 28+ (the demo uses 33.x)
• Node 18+
• Cross-platform: macOS, Windows 10 1809+, Linux (X11 / Wayland)