---
title: SDK Web
---

# SDK Web

Le SDK Web prend en charge tous les navigateurs modernes avec plusieurs méthodes d'intégration.

::: tip Voyez-le fonctionner en 30 secondes
[demo-v1.captcha.la](https://demo-v1.captcha.la) — HTML + PHP pur, sous licence MIT, code source consultable sur chaque page.

- [popup.html](https://demo-v1.captcha.la/popup.html) — mode popup
- [float.html](https://demo-v1.captcha.la/float.html) — widget flottant
- [bind.html](https://demo-v1.captcha.la/bind.html) — lié à un bouton
- [inline.html](https://demo-v1.captcha.la/inline.html) — intégration en ligne
- [server-token.html](https://demo-v1.captcha.la/server-token.html) — token émis par le serveur (anti-rejeu)
:::

## Démarrage rapide

```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';
```

## Modes

### Mode popup

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

### Mode flottant

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

### Mode bind

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

### Mode embed

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

## Options communes

| Paramètre | Type | Valeur par défaut | Description |
| --- | --- | --- | --- |
| `appKey` | string | — | Clé d'application (obligatoire) |
| `product` | string | `popup` | Mode d'affichage : popup | float | embed | bind |
| `action` | string | `default` | Scène métier (par ex. login, register, pay). Le serveur applique des politiques de sécurité différentes selon la scène. |
| `lang` | string | `auto` | Étiquette BCP-47 (par ex. `en`, `ja`, `pt-BR`) ou `auto` pour suivre `navigator.language`. Voir [Langues prises en charge](/supported-languages) — 54 locales. |
| `serverToken` | string | — | Token à usage unique (sct_xxx) émis par votre serveur. Fortement recommandé en production — empêche les abus de rafraîchissement illimité du challenge. |
| `onServerTokenExpired` | `() => Promise<string>` | — | Appelé lorsque le serverToken expire ; renvoyez-en un nouveau pour que le SDK puisse continuer sans interrompre le flux. |
| `enableVoice` | boolean | `true` | Affiche le point d'entrée du CAPTCHA audio (prise en charge de l'accessibilité pour les utilisateurs malvoyants). |

## Validation côté serveur

Après `onSuccess`, envoyez `res.token` (préfixe `pt_`) à votre propre backend, puis validez-le côté serveur :

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

Consultez la [Référence de l'API](./api-reference) pour l'endpoint de validation complet.