Electron SDK

Electron SDK tamamen main process'te çalışır ve native, OS tarafından yönetilen bir CAPTCHA penceresi açar. Renderer doğrulamaya hiçbir zaman dokunmaz — güvenlik için bunu böyle tutun.

GitHub'da demo

📦

Captcha-La/electron-demo — her entegrasyon adımını içeren tam çalıştırılabilir örnek.

Kurulum

npm install @captchala/electron

Paket, Electron 28+ (demo ^33.0.0 sürümüne sabitlenmiştir) ve Node 18+ hedefler. Demoyu uçtan uca çalıştırmak için:

npm install
npm start

Hızlı başlangıç

// 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 yüzeyi

Sembol	Amaç
new CaptchalaClient({...})	Tek seferlik bir istemci oluşturun. appKey, serverToken, action, lang, theme, timeoutMs, retryCount ve olay işleyicilerini geçirin.
await client.verify()	Yerel CAPTCHA penceresini açar. Başarıda bir sonuçla çözülür, sert hatada reddedilir.
onReady / onFail	Yapıcıya geçirilen isteğe bağlı işleyiciler. onFail, kurtarılabilir hatalar içindir (SDK yeniden dener).
result.passToken	Backend'inizde doğrulanacak token. İstemci için her zaman opak.
client.destroy()	Pencereyi kapatır ve kaynakları serbest bırakır. Bir istemci örneğini bitirdiğinizde her zaman çağırın.
CaptchalaClient.version()	SDK sürüm dizgisini döndüren statik yardımcı. Destek / debug katmanlarında kullanışlıdır.

Sunucu tarafı doğrulama

result.passToken (veya result.token) değerini backend'inize iletip CaptchaLa API'sine karşı doğrulayın. X-App-Secret değerini asla istemci kodunda açmayın.

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

Tam doğrulama uç noktası ve X-App-Key / X-App-Secret akışı için API Referansı'na bakın.

Sorun giderme

• SDK'yı renderer'a import etmeyin
  @captchala/electron yalnızca main process içindir. Sonucu, demonun preload.js dosyasındaki gibi contextBridge + ipcRenderer.invoke() aracılığıyla açın. nodeIntegration: false ve contextIsolation: true tutun.

• Çalışma zamanında modül bulunamadı
  @captchala/electron normal bir bağımlılıktır, devDependency değildir — son uygulamanıza paketlenmelidir. electron-builder gibi paketleyiciler bunu otomatik olarak dahil eder.

• Pencere ana pencerenizin arkasında açılıyor
  Bu bir Linux/X11 tuhaflığıdır. CAPTCHA penceresini sarıyorsanız kendi BrowserWindow'unuzda parent geçirin veya verify() döndükten sonra mainWindow.focus() çağırın.

• Electron 28+ gerekli
  Demo, electron: ^33.0.0 bildirir. Daha eski Electron, SDK'nın güvendiği API'leri kaçırabilir; 28+ ve Node 18+ değerlerine sabitleyin.

Gereksinimler

• Electron 28+ (demo 33.x kullanır)
• Node 18+
• Çapraz platform: macOS, Windows 10 1809+, Linux (X11 / Wayland)