> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK JavaScript de vérification d'identité : KYC web

> SDK JavaScript Didit pour KYC, KYB, AML et vivacité. Intégré, redirection ou iframe. Dès $0.33 par KYC complet, $10 offerts/mois, sans contrat.



Prompt d'intégration du SDK JavaScript
        Copier le prompt dans le presse-papiers



      
      

\<pre>

\`Integrate Didit identity verification into my web application using the JavaScript SDK.

\## Setup
Install: npm install @didit-protocol/sdk-web
Or CDN: <script src="https://unpkg.com/@didit-protocol/sdk-web/dist/didit-sdk.umd.min.js"></script>

\## Integration Flow
1\. (Option A — UniLink) Use a fixed UniLink URL from the Didit Console (no backend needed)
2\. (Option B — API session) Backend creates a session via POST /v3/session/ → 201 response includes "url"
3\. Frontend calls DiditSdk.shared.startVerification({ url }) — the SDK opens a modal (or inline if embedded mode)
4\. On completion, the SDK invokes DiditSdk.shared.onComplete(result) with type "completed" | "cancelled" | "failed"
5\. Backend receives full signed decision via webhook (status.updated)

\## Frontend Code — Vanilla JS / TypeScript
import { DiditSdk } from '@didit-protocol/sdk-web';

DiditSdk.shared.onComplete = (result) => {
switch (result.type) {
case 'completed':
  // result.session.status: "Approved" | "Pending" | "Declined"
  console.log('Done:', result.session.sessionId, result.session.status);
  break;
case 'cancelled':
  console.log('User cancelled');
  break;
case 'failed':
  console.error('Failed:', result.error.type, result.error.message);
  break;
}
};

// Modal mode (default)
DiditSdk.shared.startVerification({
url: 'https://verify.didit.me/session/SESSION_TOKEN' // from backend OR UniLink
});

// Inline / embedded mode
DiditSdk.shared.startVerification({
url: 'https://verify.didit.me/session/SESSION_TOKEN',
configuration: { embedded: true, embeddedContainerId: 'didit-container' }
});

\## Frontend Code — React
function VerifyButton({ userId }) {
const [loading, setLoading] = useState(false);

async function handleVerify() {
setLoading(true);
const res = await fetch('/api/create-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ user_id: userId })
});
const { url } = await res.json(); // OpenAPI field is named "url"

const { DiditSdk } = await import('@didit-protocol/sdk-web');
DiditSdk.shared.onComplete = (result) => {
  if (result.type === 'completed') {
    // update UI; final, signed result arrives on backend via webhook
  }
  setLoading(false);
};
DiditSdk.shared.startVerification({ url });
}

return <button onClick={handleVerify} disabled={loading}>Verify Identity</button>;
}

\## Backend: Create Session
POST https://verification.didit.me/v3/session/
Headers: { "x-api-key": DIDIT_API_KEY, "Content-Type": "application/json" }
Body: { "workflow_id": DIDIT_WORKFLOW_ID, "callback": "https://myapp.com/done", "vendor_data": userId }
Returns 201 (all 10 fields, per OpenAPI):
\{
"session_id": "uuid",
"session_number": 43762,
"session_token": "3FaJ9wLqX2Mz",   // 12-char URL-safe token; valid until the session expires
"url": "https://verify.didit.me/session/3FaJ9wLqX2Mz",
"vendor_data": "userId",
"metadata": null,
"status": "Not Started",
"workflow_id": "uuid",
"workflow_version": 3,
"callback": "https://myapp.com/done"
}
Pass the "url" field to DiditSdk.shared.startVerification({ url }) — never build the URL by hand.
(If the request sets "language", the URL gains a language segment: https://verify.didit.me/es/session/...)

\## SDK Surface (singleton — DiditSdk.shared)
Methods:  startVerification(options), close(), destroy()
Callbacks: onComplete(result), onStateChange(state, error?), onEvent(event)
State enum: 'idle' | 'loading' | 'ready' | 'error'

\## Rate Limits
600 session-create requests per minute per API key (falls back to bearer token, then client IP), plus a shared budget of 300 write (POST/PATCH/DELETE) requests per minute across all endpoints — the 300/min budget is exhausted first. Exceeding either returns HTTP 429 with Retry-After.

\## Environment Variables
\- DIDIT_API_KEY — backend only (Didit Console > API & Webhooks)
\- DIDIT_WORKFLOW_ID — backend only (Didit Console > Workflows)
\- Never expose the API key on the frontend — the session_token embedded in "url" is the only credential the SDK needs. It grants access to that one session's flow (valid until the session expires), so don't log or share it either.

\## Docs
\- JavaScript SDK: https://docs.didit.me/integration/web-sdks/javascript-sdk
\- Create Session API: https://docs.didit.me/sessions-api/create-session
\- Webhooks: https://docs.didit.me/integration/webhooks`

\</pre>



      
      

Coller dans

Le SDK JavaScript de Didit vous permet d'intégrer la vérification à votre application web de manière programmatique, avec un contrôle total sur l'expérience utilisateur.***## Fonctionnalités- **API simple** : motif singleton avec des méthodes faciles à utiliser
- **Intégration flexible** : utilisez directement l'URL UniLink ou créez des sessions via votre backend
- **Adaptatif** : fonctionne sur les navigateurs de bureau et mobiles
- **Personnalisable** : options de configuration pour le style et le comportement
- **Formats multiples** : versions compilées ESM, CommonJS et UMD
- **Prise en charge de TypeScript** : définitions de types complètes incluses
- **Modes modal et intégré** : choisissez entre une superposition modale et une intégration en ligne
- **Callbacks d'événements** : événements en temps réel sur la progression de la vérification (démarrée, étape terminée, terminée)
- **Gestion d'état** : observez l'état du SDK pour créer une interface personnalisée***## Installation### NPM/Yarn```bash theme={null}
npm install @didit-protocol/sdk-web
# or
yarn add @didit-protocol/sdk-web
```### CDN (UMD)```html theme={null}
<script src="https://unpkg.com/@didit-protocol/sdk-web/dist/didit-sdk.umd.min.js"></script>
```> [!NOTE]
>
> La dernière version publiée sur npm est `0.5.1`.
> `0.5.0` a ajouté `DiditSdk.shared.submitEvent()` (voir [Envoyer des événements](#envoi-d’événements)), et `0.5.1` permet au flux hébergé de demander à un portefeuille d'identité numérique la pièce d'identité de l'utilisateur à l'intérieur du SDK. Un lancement échoué reste dans l'état `error`, avec son `errorMessage`.
> `0.4.0` a ajouté les options de caméra que proposent déjà les SDK natifs, dont `defaultLivenessCamera`, qui ouvre la capture du visage sur la caméra arrière (voir [Options de caméra](#options-de-caméra)).### Vérifier la version installéeVotre gestionnaire de paquets reste la référence pour la version installée :```bash theme={null}
npm list @didit-protocol/sdk-web
npm view @didit-protocol/sdk-web version
```Vous pouvez aussi inspecter l'export à l'exécution :```typescript theme={null}
const { SDK_VERSION } = await import('@didit-protocol/sdk-web');

console.log(SDK_VERSION);
```À partir de `0.3.1`, cet export est généré à partir de la version du package dans chaque format JavaScript (ESM, CommonJS, UMD, UMD minifié) ainsi que dans la déclaration TypeScript. Il correspond donc toujours à la version installée.Les versions `0.3.0` et antérieures renvoient `0.2.1` depuis cet export, quelle que soit la version installée. Sur ces versions, utilisez `npm list` ou votre fichier de verrouillage à la place.***## JavaScript natif### Modules ES / TypeScript```typescript theme={null}
import { DiditSdk } from '@didit-protocol/sdk-web';

// Set up completion callback
DiditSdk.shared.onComplete = (result) => {
  switch (result.type) {
    case 'completed':
      console.log('Verification completed!');
      console.log('Session ID:', result.session?.sessionId);
      console.log('Status:', result.session?.status);
      break;
    case 'cancelled':
      console.log('User cancelled verification');
      break;
    case 'failed':
      console.error('Verification failed:', result.error?.message);
      break;
  }
};

// Start verification with the `url` returned by POST /v3/session/ (or your UniLink)
DiditSdk.shared.startVerification({
  url: 'https://verify.didit.me/session/3FaJ9wLqX2Mz'
});
```### Balise script (UMD)```html theme={null}
<script src="https://unpkg.com/@didit-protocol/sdk-web/dist/didit-sdk.umd.min.js"></script>
<script>
  const { DiditSdk } = DiditSDK;

  DiditSdk.shared.onComplete = (result) => {
    if (result.type === 'completed') {
      alert('Verification completed: ' + result.session.status);
    }
  };

  function startVerification() {
    DiditSdk.shared.startVerification({
      // You can get this link by clicking on "copy link" in the workflows view
      url: 'https://verify.didit.me/u/WORKFLOW_ID_IN_BASE_64'
    });
  }
</script>

<button onclick="startVerification()">Verify Identity</button>
```***## Exemples par framework> [card] [Exemples web du SDK](https://github.com/didit-protocol/sdk-web-examples)
>
> React, Angular, Svelte, Next.js, Nuxt, Vue, et bien d'autres, avec des exemples et de la documentation pour chaque framework.***## Méthodes d'intégrationIl existe deux façons d'intégrer le SDK :### Méthode 1 : URL UniLink (la plus simple)Utilisez directement l'URL UniLink de votre workflow depuis la Console Didit. Aucun backend n'est requis.```typescript theme={null}
DiditSdk.shared.startVerification({
  // You can get this link by clicking on "copy link" in the workflows view
  url: 'https://verify.didit.me/u/WORKFLOW_ID_IN_BASE_64'
});
```Récupérez votre URL UniLink depuis la [Console Didit](https://business.didit.me) → Votre workflow → Copier le lien.**Le session\_id généré vous sera transmis par un événement.**
**[Consultez la référence des événements ici](#référence-des-événements)**### Méthode 2 : session côté backend (recommandée en production)Votre backend crée une session via l'API Didit et renvoie l'URL de vérification hébergée. Cela vous permet de contrôler `vendor_data`, le `callback` par session et `metadata`, et de créer des sessions avant que l'utilisateur n'atteigne le frontend.Pour en savoir plus, consultez la [référence de l'API Create Session](https://docs.didit.me/fr/sessions-api/create-session.md).**Backend (Node.js / Express)**```javascript theme={null}
import express from 'express';
const app = express();
app.use(express.json());

app.post('/api/create-session', async (req, res) => {
  const response = await fetch('https://verification.didit.me/v3/session/', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DIDIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: req.body.userId,             // links the session to your user
      callback: 'https://yourapp.com/verified', // optional — overrides workflow default
    }),
  });

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  // 201 response fields (per OpenAPI): session_id, session_number, session_token, url,
  // vendor_data, metadata, status, workflow_id, workflow_version, callback
  const session = await response.json();
  res.json({ session_id: session.session_id, url: session.url });
});
```**Frontend**```typescript theme={null}
import { DiditSdk } from '@didit-protocol/sdk-web';

const res = await fetch('/api/create-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId: 'user-123' }),
});
const { url } = await res.json();

DiditSdk.shared.startVerification({
  url,
  configuration: {
    loggingEnabled: true,
  },
});
```> [!NOTE]
>
> Le champ de réponse de création de session se nomme `url` (voir le [schéma OpenAPI de Create Session](https://docs.didit.me/fr/sessions-api/create-session.md)). Transmettez-le directement à `startVerification({ url })`.***## Configuration| Option | Type | Valeur par défaut | Description |
| - | - | - | - |
| `loggingEnabled` | `boolean` | `false` | Active la journalisation du SDK pour le débogage |
| `containerElement` | `HTMLElement` | `document.body` | Élément conteneur personnalisé dans lequel monter la modale |
| `zIndex` | `number` | `9999` | Valeur z-index de la superposition modale |
| `showCloseButton` | `boolean` | `true` | Affiche le bouton de fermeture sur la modale |
| `showExitConfirmation` | `boolean` | `true` | Affiche une boîte de dialogue de confirmation lors de la fermeture |
| `closeModalOnComplete` | `boolean` | `false` | Ferme automatiquement la modale lorsque la vérification se termine |
| `embedded` | `boolean` | `false` | Affiche la vérification en ligne au lieu d'une superposition modale |
| `embeddedContainerId` | `string` | — | ID de l'élément conteneur pour le mode intégré (obligatoire lorsque `embedded` vaut `true`) |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Caméra qui s'ouvre en premier pour la capture du document. Voir [Options de caméra](#options-de-caméra) |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Caméra qui s'ouvre en premier pour la capture du visage (détection du vivant). Voir [Options de caméra](#options-de-caméra) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Affiche le bouton de changement de caméra pendant la capture à l'étape du document |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Affiche le bouton de changement de caméra pendant la capture à l'étape de détection du vivant |> [!TIP]
>
> Consultez ci-dessous les [définitions complètes des types TypeScript](#types-typescript) de l'interface `DiditSdkConfiguration`.***## Options de caméra> [!NOTE]
>
> Les options de caméra nécessitent `@didit-protocol/sdk-web`**0.4.0** ou une version ultérieure.Le SDK web expose les mêmes quatre options de caméra que les [SDK natifs](https://docs.didit.me/fr/integration/native-sdks/overview.md). Par défaut, la capture du document ouvre la caméra arrière et la capture du visage (détection du vivant) ouvre la caméra frontale (selfie). Les deux étapes proposent un bouton de changement de caméra pendant la capture sur les appareils disposant de plusieurs caméras. Définissez `defaultLivenessCamera: 'back'` pour ouvrir la capture du visage avec la caméra arrière, par exemple sur une borne ou lorsqu'un opérateur tient l'appareil et le pointe vers la personne à vérifier.| Option | Type | Par défaut | Description |
| - | - | - | - |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Objectif utilisé lors de l'ouverture de l'écran de capture du document |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Objectif utilisé lors de l'ouverture de l'écran de détection du vivant (visage passif) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Affiche le bouton de changement de caméra pendant la capture sur l'écran du document ; `false` verrouille l'utilisateur sur `defaultDocumentCamera` |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Affiche le bouton de changement de caméra pendant la capture sur l'écran de détection du vivant ; `false` verrouille l'utilisateur sur `defaultLivenessCamera` |```typescript theme={null}
// A kiosk: the operator points the device at the person, on the rear camera, with no way to switch
DiditSdk.shared.startVerification({
  url,
  configuration: {
    defaultLivenessCamera: 'back',
    showLivenessCameraSwitchButton: false
  }
});
```- Les valeurs d'objectif acceptées sont `'front'` et `'back'`. Toute autre valeur est ignorée, de même qu'un indicateur de bouton de changement qui n'est pas un booléen.
- Un appareil qui ne dispose pas de la caméra demandée utilise celle dont il dispose : un ordinateur portable qui demande `'back'` utilise toujours sa webcam. Le bouton de changement est masqué sur les appareils à caméra unique, quelles que soient les options.
- Les options de détection du vivant s'appliquent à la vérification passive du vivant. La détection du vivant active n'est pas concernée.
- Le SDK transmet les options à la page de vérification sous forme de paramètres de requête de l'URL de vérification : `document_camera`, `liveness_camera`, `document_camera_switch` et `liveness_camera_switch`. Si vous ouvrez directement l'URL de vérification au lieu de passer par le SDK, définissez-les vous-même : ajoutez `?liveness_camera=back` à une URL sans chaîne de requête, ou `&liveness_camera=back` à une URL qui contient déjà des paramètres. Vous pouvez aussi utiliser l'API `URL`, qui gère les deux cas :```typescript theme={null}
const verificationUrl = new URL(url);
verificationUrl.searchParams.set('liveness_camera', 'back');
verificationUrl.searchParams.set('liveness_camera_switch', 'false');
window.location.assign(verificationUrl.toString());
```***## Envoi d'événements`DiditSdk.shared.submitEvent()` met en file d'attente les événements de l'utilisateur final (inscription, connexion, échec de connexion, déconnexion, réinitialisation du mot de passe, MFA, changement d'appareil) pour la surveillance des événements de Didit.
Votre backend génère un token de surveillance pour la personne, et le SDK envoie les événements par lots avec l'empreinte de l'appareil.
Ne transmettez jamais de clé API au navigateur.```typescript theme={null}
DiditSdk.shared.submitEvent({
  monitoringToken, // minted by your backend for this person
  event: { category: "auth", actionType: "login", payload: { method: "password" } },
});
```Consultez [Envoi d'événements du SDK](https://docs.didit.me/fr/transaction-monitoring/sdk-event-submission.md) pour le token, les champs d'événement et le comportement de livraison.***## Dimensionnement de la modale et défilement> [!NOTE]
>
> Le comportement de dimensionnement décrit ci-dessous nécessite la version **0.3.1** ou une version ultérieure. Les versions **0.3.0** et antérieures peuvent tronquer le parcours de vérification sur les fenêtres d'affichage de bureau et en mode paysage lorsque leur hauteur est réduite.Le mode modal utilise une largeur maximale de 500px et une hauteur maximale de 700px. Sur les fenêtres d'affichage de bureau et en mode paysage lorsque leur hauteur est réduite, l'iframe occupe 90 % de la fenêtre d'affichage visible. Le parcours de vérification défile à l'intérieur de l'iframe, de sorte que chaque étape reste accessible tandis que la page située derrière la modale reste verrouillée.Le SDK utilise `dvh` sur les navigateurs qui prennent en charge les unités de fenêtre d'affichage dynamiques, et revient à `vh` sur les anciens navigateurs pris en charge. Pour des largeurs de 540px et moins, la modale occupe toute la fenêtre d'affichage visible. Le bouton de fermeture et la confirmation de sortie restent à l'intérieur de la modale.### Parcours de vérification repensé> [!NOTE]
>
> Tout le contenu de cette section s'applique à partir de la version **0.5.0**, qui n'est pas encore publiée. Tant que vous n'effectuez pas la mise à niveau, la modale conserve la taille décrite ci-dessus.À partir de la version 0.5.0, la modale se dimensionne en fonction du parcours de vérification repensé, une fois que la page signale sa mise en page avec un [message `didit:layout`](https://docs.didit.me/fr/integration/web-sdks/incontext-iframe#dimensionner-l’iframe-avec-diditlayout) :| Largeur de la fenêtre | Modale (à partir de la version 0.5.0) |
| - | - |
| 1024px et plus | 960px sur 660px à chaque étape, au maximum 90 % de la largeur et de la hauteur de la fenêtre |
| 541px à 1023px | 500px de large et aussi haute que le contenu de la page, au maximum 90 % de la hauteur de la fenêtre |
| 540px et moins | Plein écran |- **Taille initiale, à partir de la version 0.5.0 :** tant que la page ne signale pas sa mise en page, et pour les pages qui ne le font jamais, la modale conserve la taille maximale existante de 500px sur 700px. Elle reste adaptée aux fenêtres basses et passe en plein écran à 540px et moins.
- **Bouton de fermeture, à partir de la version 0.5.0 :** un cercle de 44px par-dessus la barre supérieure de la page. Il suit le thème clair ou sombre de la page et se place à gauche dans les langues écrites de droite à gauche.
- **Mode intégré, à partir de la version 0.5.0 :** il continue de remplir son élément hôte, comme auparavant (voir [Mode intégré](#mode-intégré)).
- **URL de vérification, à partir de la version 0.5.0 :** le SDK ajoute `sdk_presentation` (`modal` ou `embedded`) et, dans une modale, `sdk_close_button` (`true` ou `false`, selon `showCloseButton`), afin que la page sache comment elle est affichée.
- **Événements, à partir de la version 0.5.0 :** le SDK gère lui-même `didit:layout` et ne le transmet pas à `onEvent`.Il n'y a rien à configurer, et toutes les options existantes continuent de fonctionner.***## Mode intégréLe mode intégré n'utilise pas la limite de 500px sur 700px de la modale. Le SDK remplit la zone de contenu de l'élément hôte ; donnez donc à cet élément une hauteur explicite ou résolue d'une autre manière :```html theme={null}
<div id="verification-container" style="width: 500px; height: 700px;"></div>
``````typescript theme={null}
DiditSdk.shared.startVerification({
  url: 'https://verify.didit.me/u/...',
  configuration: {
    embedded: true,
    embeddedContainerId: 'verification-container'
  }
});
```Si l'hôte n'a pas de hauteur résolue, l'iframe intégrée n'a pas non plus de hauteur utilisable. Redimensionnez l'hôte lorsque votre mise en page change ; le SDK continue de le remplir automatiquement.***## Résultats de vérificationLe SDK renvoie trois types de résultats :### TerminéLe flux de vérification est terminé (approuvé, en attente ou refusé).```typescript theme={null}
{
  type: 'completed',
  session: {
    sessionId: 'session-uuid',
    status: 'Approved' | 'Pending' | 'Declined'
  }
}
```> [!NOTE]
>
> Le type TypeScript déclare `'Approved' | 'Pending' | 'Declined'`, mais la valeur est transmise telle quelle depuis le statut de session du flux hébergé : vous pouvez aussi recevoir d'autres statuts, comme `In Review`. `Pending` est la valeur de repli du SDK lorsque le flux n'a signalé aucun statut. Considérez `status` comme une indication et fiez-vous au [webhook](https://docs.didit.me/fr/integration/webhooks.md) pour la décision de référence.### AnnuléL'utilisateur a fermé la modale de vérification. `session` est incluse lorsqu'un `sessionId` était déjà connu (elle peut valoir `undefined` si l'utilisateur a annulé avant que l'iframe n'en signale un).```typescript theme={null}
{
  type: 'cancelled',
  session: {
    sessionId: 'session-uuid',
    status: 'Pending'
  }
}
```### ÉchecUne erreur s'est produite pendant la vérification.```typescript theme={null}
{
  type: 'failed',
  error: {
    type: 'sessionExpired' | 'networkError' | 'cameraAccessDenied' | 'unknown',
    message: 'Your verification session has expired.'
  }
}
```***## Gestion de l'étatVous pouvez observer l'état du SDK pour une interface personnalisée :```typescript theme={null}
DiditSdk.shared.onStateChange = (state, error) => {
  switch (state) {
    case 'idle':
      // Ready to start
      break;
    case 'loading':
      // Loading verification iframe
      showLoadingSpinner();
      break;
    case 'ready':
      // Verification in progress
      hideLoadingSpinner();
      break;
    case 'error':
      // Error occurred
      showError(error);
      break;
  }
};

// Check current state
console.log(DiditSdk.shared.state);

// Check if verification is presented
console.log(DiditSdk.shared.isPresented);
```***## Référence de l'API### DiditSdk.sharedL'instance unique du SDK.### Méthodes| Méthode | Description |
| - | - |
| `startVerification(options)` | Démarrer le flux de vérification |
| `submitEvent(options)` | Mettre en file d'attente un événement utilisateur final pour la surveillance des événements, avec un token de surveillance |
| `close()` | Fermer par programmation la modale de vérification |
| `destroy()` | Détruire l'instance du SDK et nettoyer les ressources |### Propriétés| Propriété | Type | Description |
| - | - | - |
| `state` | `DiditSdkState` | État actuel du SDK |
| `configuration` | `DiditSdkConfiguration \| undefined` | Configuration active (définie pendant qu'une vérification est en cours) |
| `isPresented` | `boolean` | Indique si la modale de vérification est ouverte |
| `errorMessage` | `string \| undefined` | Message d'erreur (défini lorsque l'état vaut `error`) ; un lancement échoué reste à `error` jusqu'à ce que vous lanciez à nouveau une vérification |### Fonctions de rappel| Rappel | Paramètres | Description |
| - | - | - |
| `onComplete` | `(result: VerificationResult)` | Appelé lorsque la vérification se termine |
| `onStateChange` | `(state: DiditSdkState, error?: string)` | Appelé à chaque changement d'état |
| `onEvent` | `(event: VerificationEvent)` | Appelé pour chaque événement de vérification détaillé |***## Événements granulairesSuivez la progression de la vérification avec la fonction de rappel `onEvent` :```typescript theme={null}
DiditSdk.shared.onEvent = (event) => {
  console.log('Event:', event.type, event.data);
};
```### Référence des événements| Événement | Description | Données transmises |
| - | - | - |
| `didit:ready` | La page est prête et le sessionId est disponible | `{ sessionId }` |
| `didit:started` | L'utilisateur a commencé la vérification | `{ sessionId? }` |
| `didit:step_started` | Une étape de vérification a commencé | `{ step, sessionId? }` |
| `didit:step_completed` | Une étape s'est terminée avec succès | `{ step, nextStep?, sessionId? }` |
| `didit:step_changed` | L'étape en cours a changé | `{ step, previousStep?, sessionId? }` |
| `didit:media_started` | La capture par caméra ou d'un média a commencé | `{ step, mediaType }` |
| `didit:media_captured` | Photo ou vidéo capturée | `{ step, isAuto }` |
| `didit:document_selected` | L'utilisateur a sélectionné le type de document et le pays | `{ documentType, country }` |
| `didit:verification_submitted` | Données envoyées pour traitement | `{ step, sessionId? }` |
| `didit:code_sent` | Code OTP envoyé | `{ step, channel?, codeSize?, sessionId? }` |
| `didit:code_verified` | Code OTP vérifié | `{ step, sessionId? }` |
| `didit:status_updated` | Le statut de la session a changé | `{ status, previousStep?, sessionId? }` |
| `didit:completed` | Flux de vérification terminé | `{ sessionId?, status?, country?, documentType? }` |
| `didit:cancelled` | L'utilisateur a annulé la vérification | `{ sessionId? }` |
| `didit:error` | Une erreur s'est produite | `{ error: string, step?, sessionId? }` |
| `didit:close_request` | L'utilisateur a demandé la fermeture de la modale | (aucune donnée) |### Connexion perdueSi la connexion de l'utilisateur est interrompue, la page de vérification affiche un écran « Pas de connexion Internet » à la place de l'étape en cours, au lieu de laisser une étape en chargement.
Elle continue de vérifier la connexion en arrière-plan et ferme l'écran automatiquement dès que Didit redevient accessible. L'utilisateur reprend alors à l'étape où il se trouvait.
Dans la modale du SDK ou dans une iframe, l'écran propose aussi **Quitter la vérification**. La page envoie alors `didit:error` avec `error: "network_error"`, suivi de `didit:cancelled`, et le SDK ferme la modale et appelle `onComplete` avec `type: "cancelled"`.À partir de la version 0.5.0, le message `didit:layout` de la page dimensionne la modale et n'atteint pas `onEvent`. Si vous intégrez la page avec votre propre iframe, consultez [Dimensionner l'iframe à partir de `didit:layout`](https://docs.didit.me/fr/integration/web-sdks/incontext-iframe#dimensionner-l’iframe-avec-diditlayout).### Valeurs de l'étapeLe champ `step` peut prendre l'une des valeurs suivantes :- `document_selection` - Sélection du type de document
- `document_front` - Recto du document
- `document_back` - Verso du document
- `face` - Vérification faciale et détection du vivant
- `email` - Vérification de l'e-mail
- `phone` - Vérification du téléphone
- `poa` - Justificatif de domicile
- `questionnaire` - Étape du questionnaire### Valeurs du canalLe champ `channel` de `code_sent` peut prendre les valeurs suivantes :- `email` - Code envoyé par e-mail
- `sms` - Code envoyé par SMS
- `whatsapp` - Code envoyé par WhatsApp### Taille du codeLe champ `codeSize` de `code_sent` indique la longueur du code OTP (par exemple 4 ou 6 chiffres).***## Types TypeScript```typescript theme={null}
// Configuration types
interface DiditSdkConfiguration {
  /**
   * Enable SDK logging for debugging
   * @default false
   */
  loggingEnabled?: boolean;

  /**
   * Custom container element to mount the modal
   * @default document.body
   */
  containerElement?: HTMLElement;

  /**
   * Z-index for the modal overlay
   * @default 9999
   */
  zIndex?: number;

  /**
   * Show close button on modal
   * @default true
   */
  showCloseButton?: boolean;

  /**
   * Show exit confirmation dialog when closing
   * @default true
   */
  showExitConfirmation?: boolean;

  /**
   * Automatically close modal when verification completes
   * @default false
   */
  closeModalOnComplete?: boolean;

  /**
   * Render verification inline instead of modal overlay
   * @default false
   */
  embedded?: boolean;

  /**
   * Container element ID for embedded mode
   * Required when embedded is true
   */
  embeddedContainerId?: string;

  /**
   * Camera the document capture opens first.
   * @default 'back'
   */
  defaultDocumentCamera?: CameraLens;

  /**
   * Camera the face (liveness) capture opens first.
   * Applies to passive liveness; devices without a rear camera keep the front one.
   * @default 'front'
   */
  defaultLivenessCamera?: CameraLens;

  /**
   * Show the in-capture camera switcher on the document step.
   * false locks the user to defaultDocumentCamera.
   * @default true
   */
  showDocumentCameraSwitchButton?: boolean;

  /**
   * Show the in-capture camera switcher on the liveness step.
   * false locks the user to defaultLivenessCamera.
   * @default true
   */
  showLivenessCameraSwitchButton?: boolean;
}

type CameraLens = 'front' | 'back';

// Session + error types
type VerificationStatus = 'Approved' | 'Pending' | 'Declined';

interface SessionData {
  sessionId: string;
  status: VerificationStatus;
}

type VerificationErrorType =
  | 'sessionExpired'
  | 'networkError'
  | 'cameraAccessDenied'
  | 'unknown';

interface VerificationError {
  type: VerificationErrorType;
  message: string;
}

// Verification result — `session` and `error` are both optional fields
// on every result; which one is populated depends on `type`.
type VerificationResultType = 'completed' | 'cancelled' | 'failed';

interface VerificationResult {
  type: VerificationResultType;
  session?: SessionData;
  error?: VerificationError;
}

// State types
type DiditSdkState = 'idle' | 'loading' | 'ready' | 'error';

// Event types
type VerificationEventType =
  | 'didit:ready'
  | 'didit:started'
  | 'didit:step_started'
  | 'didit:step_completed'
  | 'didit:step_changed'
  | 'didit:media_started'
  | 'didit:media_captured'
  | 'didit:document_selected'
  | 'didit:verification_submitted'
  | 'didit:code_sent'
  | 'didit:code_verified'
  | 'didit:status_updated'
  | 'didit:completed'
  | 'didit:cancelled'
  | 'didit:error'
  | 'didit:close_request';

interface VerificationEventData {
  sessionId?: string;
  status?: string;
  step?: string;
  nextStep?: string;
  previousStep?: string;
  error?: string;
  country?: string;
  documentType?: string;
  isAuto?: boolean;
  mediaType?: string;
  channel?: string;
  codeSize?: number;
  [key: string]: unknown;
}

interface VerificationEvent {
  type: VerificationEventType;
  data?: VerificationEventData;
  timestamp?: number;
}

// Start verification options
interface StartVerificationOptions {
  url: string;
  configuration?: DiditSdkConfiguration;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.