> ## 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.

# JavaScript-SDK für Identitätsverifizierung: Web-KYC

> Didits JavaScript-SDK für KYC, KYB, AML und Liveness. Eingebettet, Redirect oder iFrame. Ab $0.33/Check, $10 gratis/Monat, ohne Vertrag.



Prompt zur Integration des JavaScript-SDK
        Prompt in die Zwischenablage kopieren



      
      

\<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>



      
      

Einfügen in

Das Didit JavaScript-SDK bietet eine programmatische Möglichkeit, Verifizierungen mit voller Kontrolle über das Benutzererlebnis in Ihre Webanwendung zu integrieren.***## Funktionen- **Einfache API** – Singleton-Muster mit benutzerfreundlichen Methoden
- **Flexible Integration** – Verwenden Sie die UniLink-URL direkt oder erstellen Sie Sitzungen über das Backend
- **Responsiv** – Funktioniert in Desktop- und mobilen Browsern
- **Anpassbar** – Konfigurationsoptionen für Styling und Verhalten
- **Mehrere Formate** – ESM-, CommonJS- und UMD-Builds
- **TypeScript-Unterstützung** – Vollständige Typdefinitionen enthalten
- **Modal- und Inline-Modus** – Wählen Sie zwischen Modal-Overlay oder Inline-Einbettung
- **Event-Callbacks** – Echtzeit-Ereignisse für den Verifizierungsfortschritt (gestartet, Schritt abgeschlossen, beendet)
- **Statusverwaltung** – Beobachten Sie den SDK-Status für eine benutzerdefinierte Benutzeroberfläche***## 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]
>
> Das neueste veröffentlichte npm-Release ist `0.5.1`.
> Mit `0.5.0` wurde `DiditSdk.shared.submitEvent()` hinzugefügt (siehe [Ereignisse senden](#ereignisse-übermitteln)), und mit `0.5.1` kann der gehostete Ablauf innerhalb des SDK eine digitale ID-Wallet nach dem Ausweis des Benutzers fragen und behält einen fehlgeschlagenen Start im `error`-Status mit der zugehörigen `errorMessage` bei.
> `0.4.0` hat die Kameraoptionen hinzugefügt, die die nativen SDKs bereits bieten, einschließlich `defaultLivenessCamera`, wodurch die Gesichtserfassung über die Rückkamera geöffnet wird (siehe [Kameraoptionen](#kameraoptionen)).### Installierte Version überprüfenIhr Paketmanager bleibt für das installierte Release maßgeblich:```bash theme={null}
npm list @didit-protocol/sdk-web
npm view @didit-protocol/sdk-web version
```Sie können auch den Laufzeit-Export überprüfen:```typescript theme={null}
const { SDK_VERSION } = await import('@didit-protocol/sdk-web');

console.log(SDK_VERSION);
```Ab `0.3.1` wird dieser Export aus der Paketversion in jedem JavaScript-Format (ESM, CommonJS, UMD, minifiziertes UMD) und in der TypeScript-Deklaration generiert, sodass er immer mit dem installierten Release übereinstimmt.Versionen `0.3.0` und früher geben bei diesem Export unabhängig von der installierten Version `0.2.1` zurück. Verwenden Sie bei diesen Versionen stattdessen `npm list` oder Ihre Lock-Datei.***## Vanilla JavaScript### ES-Module / 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'
});
```### Script-Tag (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>
```***## Framework-Beispiele> [card] [Web-SDK-Beispiele](https://github.com/didit-protocol/sdk-web-examples)
>
> React, Angular, Svelte, Next.js, Nuxt, Vue und mehr – mit Beispielen und Dokumentation für jedes Framework.***## IntegrationsmethodenEs gibt zwei Möglichkeiten, das SDK zu integrieren:### Methode 1: UniLink-URL (Am einfachsten)Verwenden Sie die UniLink-URL Ihres Workflows direkt aus der Didit Console. Kein Backend erforderlich.```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'
});
```Rufen Sie Ihre UniLink-URL in der [Didit Console](https://business.didit.me) → Ihr Workflow → Link kopieren ab.**Die generierte session\_id wird Ihnen über ein Ereignis übermittelt.**
**[Event-Referenz hier einsehen](#ereignisreferenz)**### Methode 2: Backend-Sitzung (für die Produktion empfohlen)Ihr Backend erstellt eine Sitzung über die Didit-API und gibt die gehostete Verifizierungs-URL zurück. Dadurch haben Sie die Kontrolle über `vendor_data`, sitzungsspezifische `callback`-Angaben und `metadata` und können Sitzungen erstellen, bevor der Benutzer das Frontend erreicht.Weitere Informationen finden Sie in der [API-Referenz zum Erstellen einer Sitzung](https://docs.didit.me/de/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]
>
> Das Antwortfeld bei der Sitzungserstellung heißt `url` (siehe das [OpenAPI-Schema zum Erstellen einer Sitzung](https://docs.didit.me/de/sessions-api/create-session.md)). Übergeben Sie es direkt an `startVerification({ url })`.***## Konfiguration| Option | Typ | Standard | Beschreibung |
| - | - | - | - |
| `loggingEnabled` | `boolean` | `false` | SDK-Protokollierung für das Debugging aktivieren |
| `containerElement` | `HTMLElement` | `document.body` | Benutzerdefiniertes Container-Element zum Einhängen des Modals |
| `zIndex` | `number` | `9999` | Z-Index für das Modal-Overlay |
| `showCloseButton` | `boolean` | `true` | Schließen-Schaltfläche im Modal anzeigen |
| `showExitConfirmation` | `boolean` | `true` | Bestätigungsdialog beim Schließen anzeigen |
| `closeModalOnComplete` | `boolean` | `false` | Modal nach Abschluss der Verifizierung automatisch schließen |
| `embedded` | `boolean` | `false` | Verifizierung inline statt als Modal-Overlay rendern |
| `embeddedContainerId` | `string` | — | ID des Container-Elements für den eingebetteten Modus (erforderlich, wenn `embedded` den Wert `true` hat) |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Kamera, die bei der Dokumenterfassung zuerst geöffnet wird. Siehe [Kameraoptionen](#kameraoptionen) |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Kamera, die bei der Gesichtserfassung (Liveness-Erkennung) zuerst geöffnet wird. Siehe [Kameraoptionen](#kameraoptionen) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Schaltfläche zum Wechseln der Kamera während des Dokumenterfassungsschritts anzeigen |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Schaltfläche zum Wechseln der Kamera während des Schritts zur Liveness-Erkennung anzeigen |> [!TIP]
>
> Unten finden Sie die vollständigen [TypeScript-Typdefinitionen](#typescript-typen) für das komplette `DiditSdkConfiguration`-Interface.***## Kameraoptionen> [!NOTE]
>
> Die Kameraoptionen erfordern `@didit-protocol/sdk-web`**0.4.0** oder höher.Das Web-SDK bietet dieselben vier Kameraoptionen wie die [nativen SDKs](https://docs.didit.me/de/integration/native-sdks/overview.md). Standardmäßig öffnet die Dokumentenerfassung die Rückkamera und die Gesichtserfassung (Liveness) die Frontkamera (Selfie-Kamera). Beide Schritte bieten auf Geräten mit mehr als einer Kamera einen Kameraumschalter während der Erfassung. Setzen Sie `defaultLivenessCamera: 'back'`, um die Gesichtserfassung mit der Rückkamera zu öffnen – beispielsweise an einem Kiosk-Terminal oder wenn ein Operator das Gerät hält und auf die zu verifizierende Person richtet.| Option | Typ | Standard | Beschreibung |
| - | - | - | - |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Verwendetes Kameraobjektiv beim ersten Aufrufen des Bildschirms zur Dokumentenerfassung |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Verwendetes Kameraobjektiv beim ersten Aufrufen des Bildschirms zur Liveness-Erfassung (passives Gesicht) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Zeigt den Kameraumschalter auf dem Dokumenten-Bildschirm an; bei `false` bleibt der Benutzer auf `defaultDocumentCamera` festgelegt |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Zeigt den Kameraumschalter auf dem Liveness-Bildschirm an; bei `false` bleibt der Benutzer auf `defaultLivenessCamera` festgelegt |```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
  }
});
```- Akzeptierte Objektivwerte sind `'front'` und `'back'`. Jeder andere Wert wird ignoriert, ebenso wie ein Umschalter-Flag, das kein boolescher Wert ist.
- Ein Gerät ohne die angeforderte Kamera behält die vorhandene bei: Ein Laptop, für den `'back'` angefordert wurde, verwendet weiterhin seine Webcam. Auf Geräten mit nur einer Kamera wird der Umschalter unabhängig von den Flags ausgeblendet.
- Die Liveness-Optionen gelten für die passive Liveness-Prüfung. Aktive Liveness ist davon nicht betroffen.
- Das SDK leitet die Optionen als Query-Parameter der Verifizierungs-URL an die Verifizierungsseite weiter: `document_camera`, `liveness_camera`, `document_camera_switch` und `liveness_camera_switch`. Wenn Sie die Verifizierungs-URL direkt statt über das SDK öffnen, legen Sie diese selbst fest: Fügen Sie an eine URL ohne Query-String `?liveness_camera=back` an, an eine URL, die bereits Parameter enthält, `&liveness_camera=back`, oder setzen Sie sie über die `URL`-API, damit beide Fälle abgedeckt sind:```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());
```***## Ereignisse übermitteln`DiditSdk.shared.submitEvent()` reiht Endbenutzer-Ereignisse (Registrierung, Login, fehlgeschlagener Login, Logout, Passwortzurücksetzung, MFA, Gerätewechsel) für die Ereignisüberwachung von Didit in eine Warteschlange ein.
Ihr Backend generiert ein Monitoring-Token für die Person, und das SDK sendet die Ereignisse gebündelt mit dem Geräte-Fingerabdruck.
Geben Sie niemals einen API-Schlüssel an den Browser weiter.```typescript theme={null}
DiditSdk.shared.submitEvent({
  monitoringToken, // minted by your backend for this person
  event: { category: "auth", actionType: "login", payload: { method: "password" } },
});
```Siehe [SDK-Ereignisübermittlung](https://docs.didit.me/de/transaction-monitoring/sdk-event-submission.md) für Informationen zum Token, zu den Ereignisfeldern und zum Zustellungsverhalten.***## Modal-Größenanpassung und Scrolling> [!NOTE]
>
> Das unten beschriebene Verhalten bei der Größenanpassung erfordert Version **0.3.1** oder höher. Bei Version **0.3.0** und früher kann der Verifizierungs-Workflow auf niedrigen Desktop- und Querformat-Viewports abgeschnitten werden.Der modale Modus verwendet eine maximale Breite von 500px und eine maximale Höhe von 700px. Auf kleineren Desktop- und Querformat-Viewports nimmt der iframe 90% des sichtbaren Viewports ein. Der Verifizierungs-Workflow scrollt innerhalb des iframes, sodass jeder Schritt erreichbar bleibt, während die Seite hinter dem Modal gesperrt bleibt.Das SDK verwendet `dvh` in Browsern, die dynamische Viewport-Einheiten unterstützen, und weicht in älteren unterstützten Browsern auf `vh` aus. Bei Breiten von 540px und darunter füllt das Modal den sichtbaren Viewport vollständig aus. Der Schließen-Button und die Bestätigung zum Verlassen verbleiben innerhalb des Modals.### Neugestalteter Verifizierungs-Workflow> [!NOTE]
>
> Alles in diesem Abschnitt gilt ab Version **0.5.0**, die noch nicht veröffentlicht wurde. Bis Sie upgraden, behält das Modal die oben beschriebene Größe bei.Ab Version 0.5.0 passt das Modal seine Größe an den neugestalteten Verifizierungs-Workflow an, sobald die Seite ihr Layout mit einer [`didit:layout`-Nachricht](https://docs.didit.me/de/integration/web-sdks/incontext-iframe#iframe-größe-anhand-von-diditlayout-festlegen) meldet:| Fensterbreite | Modal (ab Version 0.5.0) |
| - | - |
| 1024px und breiter | 960px mal 660px in jedem Schritt, maximal 90% der Breite und Höhe des Fensters |
| 541px bis 1023px | 500px breit und so hoch wie der Seiteninhalt, maximal 90% der Höhe des Fensters |
| 540px und darunter | Vollbild |- **Ausgangsgröße, ab Version 0.5.0:** Bis die Seite ihr Layout meldet, und bei Seiten, die dies nie tun, behält das Modal die bestehende Maximalgröße von 500px mal 700px bei. Es passt sich weiterhin an niedrige Fenster an und bleibt bei 540px und darunter im Vollbildmodus.
- **Schließen-Button, ab Version 0.5.0:** ein 44px großer Kreis über der oberen Leiste der Seite. Er folgt dem hellen oder dunklen Theme der Seite und wechselt bei Rechts-nach-links-Sprachen nach links.
- **Eingebetteter Modus, ab Version 0.5.0:** Er füllt weiterhin sein Host-Element vollständig aus, wie bisher (siehe [Eingebetteter Modus](#eingebetteter-modus)).
- **Verifizierungs-URL, ab Version 0.5.0:** Das SDK fügt `sdk_presentation` (`modal` oder `embedded`) und in einem Modal `sdk_close_button` (`true` oder `false`, entsprechend `showCloseButton`) hinzu, damit die Seite weiß, wie sie dargestellt wird.
- **Ereignisse, ab Version 0.5.0:** Das SDK verarbeitet `didit:layout` selbst und leitet es nicht an `onEvent` weiter.Es ist keine Konfiguration erforderlich, und jede bestehende Option funktioniert weiterhin.***## Eingebetteter ModusDer eingebettete Modus verwendet nicht die Begrenzung des Modals von 500px mal 700px. Das SDK füllt die Content-Box des Host-Elements aus. Weisen Sie diesem Element daher eine explizite oder anderweitig aufgelöste Höhe zu:```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'
  }
});
```Wenn der Host keine aufgelöste Höhe hat, verfügt auch der eingebettete iframe über keine nutzbare Höhe. Ändern Sie die Größe des Hosts, wenn sich Ihr Layout ändert; das SDK füllt ihn weiterhin automatisch aus.***## VerifizierungsergebnisseDas SDK gibt drei Arten von Ergebnissen zurück:### AbgeschlossenVerifizierungsablauf beendet (genehmigt, ausstehend oder abgelehnt).```typescript theme={null}
{
  type: 'completed',
  session: {
    sessionId: 'session-uuid',
    status: 'Approved' | 'Pending' | 'Declined'
  }
}
```> [!NOTE]
>
> Der TypeScript-Typ deklariert `'Approved' | 'Pending' | 'Declined'`, aber der Wert wird direkt aus dem Sitzungsstatus des gehosteten Flows übergeben – Sie können auch andere Status wie `In Review` erhalten. `Pending` ist der Fallback des SDKs, wenn der Flow keinen Status gemeldet hat. Betrachten Sie `status` als Hinweis und verlassen Sie sich für die verbindliche Entscheidung auf den [Webhook](https://docs.didit.me/de/integration/webhooks.md).### AbgebrochenDer Benutzer hat das Verifizierungs-Modal geschlossen. `session` ist enthalten, wenn eine `sessionId` bereits bekannt war (sie kann `undefined` sein, wenn der Benutzer abgebrochen hat, bevor der iFrame eine gemeldet hat).```typescript theme={null}
{
  type: 'cancelled',
  session: {
    sessionId: 'session-uuid',
    status: 'Pending'
  }
}
```### FehlgeschlagenWährend der Verifizierung ist ein Fehler aufgetreten.```typescript theme={null}
{
  type: 'failed',
  error: {
    type: 'sessionExpired' | 'networkError' | 'cameraAccessDenied' | 'unknown',
    message: 'Your verification session has expired.'
  }
}
```***## ZustandsverwaltungSie können den SDK-Zustand für benutzerdefinierte Benutzeroberflächen überwachen:```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);
```***## API-Referenz### DiditSdk.sharedDie Singleton-SDK-Instanz.### Methoden| Methode | Beschreibung |
| - | - |
| `startVerification(options)` | Verifizierungsablauf starten |
| `submitEvent(options)` | Ein Endbenutzer-Ereignis für das Event-Monitoring mit einem Monitoring-Token in die Warteschlange einreihen |
| `close()` | Verifizierungs-Modal programmatisch schließen |
| `destroy()` | SDK-Instanz zerstören und bereinigen |### Eigenschaften| Eigenschaft | Typ | Beschreibung |
| - | - | - |
| `state` | `DiditSdkState` | Aktueller SDK-Zustand |
| `configuration` | `DiditSdkConfiguration \| undefined` | Aktive Konfiguration (gesetzt, während eine Verifizierung läuft) |
| `isPresented` | `boolean` | Gibt an, ob das Verifizierungs-Modal geöffnet ist |
| `errorMessage` | `string \| undefined` | Fehlermeldung (gesetzt, wenn der Zustand `error` ist); ein fehlgeschlagener Start bleibt in `error`, bis Sie erneut starten |### Callbacks| Callback | Parameter | Beschreibung |
| - | - | - |
| `onComplete` | `(result: VerificationResult)` | Wird aufgerufen, wenn die Verifizierung beendet ist |
| `onStateChange` | `(state: DiditSdkState, error?: string)` | Wird bei Zustandsänderungen aufgerufen |
| `onEvent` | `(event: VerificationEvent)` | Wird bei granularen Verifizierungsereignissen aufgerufen |***## Granulare EreignisseVerfolgen Sie den Verifizierungsfortschritt mit dem `onEvent`-Callback:```typescript theme={null}
DiditSdk.shared.onEvent = (event) => {
  console.log('Event:', event.type, event.data);
};
```### Ereignisreferenz| Ereignis | Beschreibung | Daten-Payload |
| - | - | - |
| `didit:ready` | Die Seite ist bereit und die sessionId ist verfügbar | `{ sessionId }` |
| `didit:started` | Benutzer hat die Verifizierung gestartet | `{ sessionId? }` |
| `didit:step_started` | Ein Verifizierungsschritt hat begonnen | `{ step, sessionId? }` |
| `didit:step_completed` | Ein Schritt wurde erfolgreich abgeschlossen | `{ step, nextStep?, sessionId? }` |
| `didit:step_changed` | Aktueller Schritt hat sich geändert | `{ step, previousStep?, sessionId? }` |
| `didit:media_started` | Kamera-/Medienaufnahme gestartet | `{ step, mediaType }` |
| `didit:media_captured` | Foto/Video aufgenommen | `{ step, isAuto }` |
| `didit:document_selected` | Benutzer hat Dokumenttyp und Land ausgewählt | `{ documentType, country }` |
| `didit:verification_submitted` | Daten zur Verarbeitung übermittelt | `{ step, sessionId? }` |
| `didit:code_sent` | OTP-Code gesendet | `{ step, channel?, codeSize?, sessionId? }` |
| `didit:code_verified` | OTP-Code verifiziert | `{ step, sessionId? }` |
| `didit:status_updated` | Sitzungsstatus hat sich geändert | `{ status, previousStep?, sessionId? }` |
| `didit:completed` | Verifizierungs-Workflow abgeschlossen | `{ sessionId?, status?, country?, documentType? }` |
| `didit:cancelled` | Benutzer hat die Verifizierung abgebrochen | `{ sessionId? }` |
| `didit:error` | Ein Fehler ist aufgetreten | `{ error: string, step?, sessionId? }` |
| `didit:close_request` | Benutzer hat das Schließen des Modals angefordert | (keine Daten) |### VerbindungsabbruchWenn die Verbindung des Benutzers abbricht, überlagert die Verifizierungsseite den Workflow mit einem Bildschirm „Keine Internetverbindung“, anstatt einen Schritt im Ladezustand zu belassen.
Sie prüft im Hintergrund weiter und schließt den Bildschirm von selbst, sobald Didit wieder erreichbar ist, sodass der Benutzer mit dem Schritt fortfahren kann, bei dem er sich befand.
Innerhalb des SDK-Modals oder eines iFrames bietet der Bildschirm außerdem **Verifizierung beenden**: Die Seite sendet dann `didit:error` mit `error: "network_error"`, gefolgt von `didit:cancelled`, und das SDK schließt das Modal und ruft `onComplete` mit `type: "cancelled"` auf.Ab Version 0.5.0 passt die `didit:layout`-Nachricht der Seite die Größe des Modals an und wird nicht an `onEvent` weitergeleitet. Wenn Sie die Seite stattdessen mit Ihrem eigenen iFrame einbetten, siehe [Größe des iFrames über `didit:layout` anpassen](https://docs.didit.me/de/integration/web-sdks/incontext-iframe#iframe-größe-anhand-von-diditlayout-festlegen).### SchrittwerteDas Feld `step` kann einen der folgenden Werte annehmen:- `document_selection` - Auswahl des Dokumenttyps
- `document_front` - Vorderseite des Dokuments
- `document_back` - Rückseite des Dokuments
- `face` - Gesichts-/Liveness-Verifizierung
- `email` - E-Mail-Verifizierung
- `phone` - Telefonverifizierung
- `poa` - Adressnachweis
- `questionnaire` - Fragebogen-Schritt### KanalwerteDas Feld `channel` in `code_sent` kann folgende Werte haben:- `email` - Code per E-Mail gesendet
- `sms` - Code per SMS gesendet
- `whatsapp` - Code per WhatsApp gesendet### CodelängeDas Feld `codeSize` in `code_sent` gibt die Länge des OTP-Codes an (z. B. 4 oder 6 Ziffern).***## TypeScript-Typen```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.