SDK Electron

Le SDK Electron s'exécute entièrement dans le processus main, en ouvrant une fenêtre CAPTCHA native gérée par le système d'exploitation. Le renderer ne touche jamais à la vérification — gardez-le ainsi pour des raisons de sécurité.

Démo sur GitHub

📦

Captcha-La/electron-demo — exemple complet exécutable avec chaque étape d'intégration.

Installation

npm install @captchala/electron

Le package cible Electron 28+ (la démo épingle ^33.0.0) et Node 18+. Exécutez la démo de bout en bout avec :

npm install
npm start

Démarrage rapide

// 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)),
});

Surface de l'API

Symbole	Rôle
new CaptchalaClient({...})	Construit un client à usage unique. Passez appKey, serverToken, action, lang, theme, timeoutMs, retryCount, ainsi que les gestionnaires d'événements.
await client.verify()	Ouvre la fenêtre CAPTCHA native. Résout avec un résultat en cas de succès, rejette en cas d'erreur dure.
onReady / onFail	Gestionnaires optionnels passés au constructeur. onFail traite les échecs récupérables (le SDK retentera).
result.passToken	Le token à valider sur votre backend. Toujours opaque côté client.
client.destroy()	Ferme la fenêtre et libère les ressources. Appelez-le systématiquement quand vous avez fini avec une instance de client.
CaptchalaClient.version()	Helper statique qui renvoie la chaîne de version du SDK. Utile dans les overlays de support / debug.

Validation côté serveur

Transmettez result.passToken (ou result.token) à votre backend et validez-le auprès de l'API CaptchaLa. N'exposez jamais X-App-Secret dans le code client.

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

Consultez la Référence de l'API pour l'endpoint de validation complet et le flux X-App-Key / X-App-Secret.

Dépannage

• Ne pas importer le SDK dans le renderer
  @captchala/electron est réservé au processus main. Exposez son résultat via contextBridge + ipcRenderer.invoke() comme le fait le preload.js de la démo. Conservez nodeIntegration: false et contextIsolation: true.

• Module introuvable à l'exécution
  @captchala/electron est une dépendance normale, pas une devDependency — elle doit être empaquetée dans votre application finale. Les bundlers comme electron-builder l'incluent automatiquement.

• La fenêtre s'ouvre derrière votre fenêtre principale
  C'est une bizarrerie Linux/X11. Passez parent dans votre propre BrowserWindow si vous encapsulez la fenêtre du CAPTCHA, ou appelez mainWindow.focus() après le retour de verify().

• Electron 28+ requis
  La démo déclare electron: ^33.0.0. Une version d'Electron plus ancienne peut manquer d'API dont dépend le SDK ; épinglez à 28+ et Node 18+.

Prérequis

• Electron 28+ (la démo utilise 33.x)
• Node 18+
• Multi-plateforme : macOS, Windows 10 1809+, Linux (X11 / Wayland)