Electron SDK

SDK Electron berjalan sepenuhnya di main process, membuka jendela CAPTCHA native yang dikelola OS. Renderer process tidak ikut dalam alur validasi — jaga isolasi ini demi keamanan.

Demo di GitHub

📦

Captcha-La/electron-demo — contoh lengkap dan dapat dijalankan dengan seluruh langkah integrasi.

Instalasi

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

Mulai cepat

// 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({...})	Membuat klien sekali pakai. Berikan appKey, serverToken, action, lang, theme, timeoutMs, retryCount beserta handler event.
await client.verify()	Membuka jendela CAPTCHA native. Resolve dengan hasil saat sukses, reject saat error berat.
onReady / onFail	Handler opsional yang diberikan ke konstruktor. onFail untuk kegagalan yang dapat dipulihkan (SDK akan retry).
result.passToken	Token untuk divalidasi di backend Anda. Selalu opaque bagi klien.
client.destroy()	Menutup jendela dan membebaskan sumber daya. Selalu panggil setelah selesai menggunakan instance klien.
CaptchalaClient.version()	Helper statis yang mengembalikan string versi SDK. Berguna pada overlay support / debug.

Validasi sisi server

Teruskan result.passToken (atau result.token) ke backend Anda lalu validasi melalui API CaptchaLa. Jangan pernah mengekspos X-App-Secret di kode 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 Referensi API untuk endpoint validasi lengkap dan alur X-App-Key / X-App-Secret.

Pemecahan masalah

• Jangan import SDK di renderer
  @captchala/electron hanya untuk main process. Sediakan hasilnya lewat contextBridge + ipcRenderer.invoke() seperti preload.js pada demo. Pertahankan nodeIntegration: false dan contextIsolation: true.

• Modul tidak ditemukan saat runtime
  @captchala/electron adalah dependencies biasa, bukan devDependencies — harus dibundel ke aplikasi final. electron-builder menyertakannya secara otomatis.

• Jendela CAPTCHA muncul di belakang jendela utama
  Ini perilaku khas Linux/X11. Jika Anda membungkus BrowserWindow sendiri, teruskan parent, atau panggil mainWindow.focus() setelah verify() kembali.

• Membutuhkan Electron 28+
  Demo mendeklarasikan electron: ^33.0.0. Electron lebih lama bisa kehilangan API yang dibutuhkan SDK; pin ke 28+ dan Node 18+.

Persyaratan

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