Electron-SDK

Das Electron-SDK läuft vollständig im Main-Prozess und öffnet ein natives, vom Betriebssystem verwaltetes CAPTCHA-Fenster. Der Renderer kommt nie mit der Verifizierung in Berührung — und das sollte aus Sicherheitsgründen so bleiben.

Demo auf GitHub

📦

Captcha-La/electron-demo — vollständiges lauffähiges Beispiel mit allen Integrationsschritten.

Installation

npm install @captchala/electron

Das Paket zielt auf Electron 28+ ab (die Demo pinnt ^33.0.0) und Node 18+. Die Demo lässt sich Ende-zu-Ende ausführen mit:

npm install
npm start

Schnellstart

// 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-Übersicht

Symbol	Zweck
new CaptchalaClient({...})	Konstruiert einen Einmal-Client. Übergeben Sie appKey, serverToken, action, lang, theme, timeoutMs, retryCount sowie Event-Handler.
await client.verify()	Öffnet das native CAPTCHA-Fenster. Löst bei Erfolg mit einem Ergebnis auf, bei hartem Fehler wird abgelehnt.
onReady / onFail	Optionale Handler, die im Konstruktor übergeben werden. onFail ist für behebbare Fehlschläge gedacht (das SDK wiederholt den Versuch).
result.passToken	Der Token, der auf Ihrem Backend zu validieren ist. Für den Client stets opak.
client.destroy()	Schließt das Fenster und gibt Ressourcen frei. Stets aufrufen, sobald eine Client-Instanz nicht mehr benötigt wird.
CaptchalaClient.version()	Statischer Helper, der den SDK-Versions-String zurückliefert. Nützlich in Support- / Debug-Overlays.

Serverseitige Validierung

Leiten Sie result.passToken (oder result.token) an Ihr Backend weiter und validieren Sie ihn gegen die CaptchaLa-API. Geben Sie X-App-Secret niemals im Client-Code preis.

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

Siehe die API-Referenz für den vollständigen Validierungs-Endpoint und den X-App-Key / X-App-Secret-Flow.

Fehlerbehebung

• SDK nicht im Renderer importieren
  @captchala/electron ist ausschließlich für den Main-Prozess bestimmt. Leiten Sie das Ergebnis über contextBridge + ipcRenderer.invoke() durch, wie es die preload.js der Demo zeigt. Behalten Sie nodeIntegration: false und contextIsolation: true bei.

• Modul zur Laufzeit nicht gefunden
  @captchala/electron ist eine reguläre Dependency, keine devDependency — sie muss in Ihre finale App gepackt werden. Bundler wie electron-builder schließen sie automatisch ein.

• Fenster öffnet sich hinter Ihrem Hauptfenster
  Das ist eine Linux/X11-Eigenheit. Übergeben Sie parent in Ihrem eigenen BrowserWindow, falls Sie das CAPTCHA-Fenster umschließen, oder rufen Sie nach Rückkehr von verify() mainWindow.focus() auf.

• Electron 28+ erforderlich
  Die Demo deklariert electron: ^33.0.0. Älteres Electron kann APIs vermissen lassen, auf die das SDK aufbaut; pinnen Sie auf 28+ und Node 18+.

Voraussetzungen

• Electron 28+ (die Demo nutzt 33.x)
• Node 18+
• Plattformübergreifend: macOS, Windows 10 1809+, Linux (X11 / Wayland)