---
title: Electron-SDK
---

# 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

::: tip 📦
[Captcha-La/electron-demo](https://github.com/Captcha-La/electron-demo) — vollständiges lauffähiges Beispiel mit allen Integrationsschritten.
:::

## Installation

```bash
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:

```bash
npm install
npm start
```

## Schnellstart

```js
// 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());
```

```js
// 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.

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

Siehe die [API-Referenz](/de/api-reference) 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)