---
title: Web-SDK
---

# Web-SDK

Das Web-SDK unterstützt alle modernen Browser mit verschiedenen Integrationsmethoden.

::: tip In 30 Sekunden in Aktion sehen
[demo-v1.captcha.la](https://demo-v1.captcha.la) — reines HTML + PHP, MIT-lizenziert, Quelltext auf jeder Seite einsehbar.

- [popup.html](https://demo-v1.captcha.la/popup.html) — Popup-Modus
- [float.html](https://demo-v1.captcha.la/float.html) — schwebendes Widget
- [bind.html](https://demo-v1.captcha.la/bind.html) — an Button binden
- [inline.html](https://demo-v1.captcha.la/inline.html) — Inline-Einbettung
- [server-token.html](https://demo-v1.captcha.la/server-token.html) — servergenerierter Token (Anti-Replay)
:::

## Schnellstart

```html
<!-- 1. Load via CDN (or npm install captchala) -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

<button id="login-btn">Sign in</button>

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(res => sendToBackend(res.token))
  .onError(err => console.error(err.message))
  .bindTo('#login-btn');
});
</script>
```

## Installation

### CDN

```html
<!-- Recommended: auto-fallback loader, ~6 KB gzip -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>
```

### NPM

```bash
npm install captchala
# or framework wrappers
npm install @captcha-la/vue
npm install @captcha-la/react
```

```js
import Captchala from 'captchala';
import 'captchala/dist/captchala.css';
```

## Modi

### Popup-Modus

```js
Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'popup', action: 'login' })
  .bindTo('#login-btn')
  .onSuccess(res => sendToBackend(res.token));
```

### Float-Modus

```js
Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'float', action: 'browse' })
  .appendTo('#captcha-container')
  .onSuccess(res => sendToBackend(res.token));
```

### Bind-Modus

```js
Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'bind', action: 'login' })
  .bindTo('#submit-button')
  .onSuccess(res => submitForm(res.token));   // fires only after challenge passes
```

### Embed-Modus

```js
Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'embed', action: 'register' })
  .appendTo('#captcha-container')
  .onSuccess(res => sendToBackend(res.token));
```

## Allgemeine Optionen

| Parameter | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `appKey` | string | — | Application Key (erforderlich) |
| `product` | string | `popup` | Anzeigemodus: popup | float | embed | bind |
| `action` | string | `default` | Business-Szene (z. B. login, register, pay). Der Server wendet je Szene unterschiedliche Sicherheitsrichtlinien an. |
| `lang` | string | `auto` | BCP-47-Tag (z. B. `en`, `ja`, `pt-BR`) oder `auto`, um `navigator.language` zu folgen. Siehe [Unterstützte Sprachen](/de/supported-languages) — 54 Locales. |
| `serverToken` | string | — | Einmal-Token (sct_xxx), der von Ihrem Server ausgestellt wird. In der Produktion dringend empfohlen — verhindert unbegrenzten Missbrauch durch Challenge-Refresh. |
| `onServerTokenExpired` | `() => Promise<string>` | — | Wird aufgerufen, wenn der serverToken abläuft; geben Sie einen neuen zurück, damit das SDK den Flow unterbrechungsfrei fortsetzen kann. |
| `enableVoice` | boolean | `true` | Zeigt den Einstiegspunkt für das Audio-CAPTCHA an (Barrierefreiheit für sehbehinderte Nutzer). |

## Serverseitige Validierung

Senden Sie nach `onSuccess` den `res.token` (Präfix `pt_`) an Ihr eigenes Backend und validieren Sie ihn serverseitig:

```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": "<token>" }
```

Siehe die [API-Referenz](/de/api-reference) für den vollständigen Validierungs-Endpoint.