> ## 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 per verifica dell'identità: KYC web

> SDK JavaScript Didit per KYC, KYB e AML. Integrazione incorporata, redirect o iframe. Da $0.33 per KYC completo, $10 gratis al mese, senza contratti.



Prompt di integrazione dell'SDK JavaScript
        Copia il prompt negli appunti



      
      

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



      
      

Incolla in

L'SDK JavaScript di Didit offre un modo programmatico per integrare la verifica nella tua applicazione web, con pieno controllo sull'esperienza utente.***## Funzionalità- **API semplice** - Pattern singleton con metodi facili da usare
- **Integrazione flessibile** - Usa direttamente l'URL UniLink oppure crea sessioni dal backend
- **Responsive** - Funziona su browser desktop e mobile
- **Personalizzabile** - Opzioni di configurazione per stile e comportamento
- **Formati multipli** - Build ESM, CommonJS e UMD
- **Supporto TypeScript** - Definizioni dei tipi complete incluse
- **Modalità modale e inline** - Scegli tra overlay modale o integrazione inline
- **Callback degli eventi** - Eventi in tempo reale sull'avanzamento della verifica (avviata, passaggio completato, terminata)
- **Gestione dello stato** - Osserva lo stato dell'SDK per interfacce personalizzate***## Installazione### 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]
>
> L'ultima release pubblicata su npm è `0.5.1`.
> `0.5.0` ha aggiunto `DiditSdk.shared.submitEvent()` (vedi [Invio di eventi](#invio-di-eventi)), e `0.5.1` permette al flusso ospitato di richiedere all'interno dell'SDK l'ID dell'utente da un wallet di identità digitale, e mantiene un avvio non riuscito nello stato `error` con il relativo `errorMessage`.
> `0.4.0` ha aggiunto le opzioni della fotocamera già offerte dagli SDK nativi, incluso `defaultLivenessCamera`, che apre l'acquisizione del volto con la fotocamera posteriore (vedi [Opzioni della fotocamera](#opzioni-della-fotocamera)).### Verifica della versione installataIl tuo gestore dei pacchetti resta la fonte autorevole per la versione installata:```bash theme={null}
npm list @didit-protocol/sdk-web
npm view @didit-protocol/sdk-web version
```Puoi anche ispezionare l'export a runtime:```typescript theme={null}
const { SDK_VERSION } = await import('@didit-protocol/sdk-web');

console.log(SDK_VERSION);
```Dalla versione `0.3.1` questo export viene generato dalla versione del pacchetto in tutti i formati JavaScript (ESM, CommonJS, UMD, UMD minificato) e nella dichiarazione TypeScript, quindi corrisponde sempre alla release installata.Le versioni `0.3.0` e precedenti restituiscono `0.2.1` da questo export, indipendentemente dalla versione installata. Su queste release usa `npm list` oppure il tuo file di lock.***## JavaScript puro### ES Modules / 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'
});
```### Tag 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>
```***## Esempi per framework> [card] [Esempi web per SDK](https://github.com/didit-protocol/sdk-web-examples)
>
> React, Angular, Svelte, Next.js, Nuxt, Vue e altri, con esempi e documentazione per ciascun framework.***## Metodi di integrazioneCi sono due modi per integrare l'SDK:### Metodo 1: URL UniLink (il più semplice)Usa direttamente l'URL UniLink del tuo workflow dalla Didit Console. Non serve un backend.```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'
});
```Ottieni il tuo URL UniLink dalla [Didit Console](https://business.didit.me) → Il tuo workflow → Copia link.**Il session\_id generato ti verrà inviato tramite un evento.**
**[Consulta qui il riferimento degli eventi](#riferimento-agli-eventi)**### Metodo 2: sessione lato backend (consigliato per la produzione)Il tuo backend crea una sessione tramite l'API di Didit e restituisce l'URL di verifica ospitato. Questo ti consente di controllare `vendor_data`, il `callback` per sessione, i `metadata`, e di creare sessioni prima che l'utente raggiunga il frontend.Maggiori informazioni nel [riferimento dell'API Create Session](https://docs.didit.me/it/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]
>
> Il campo della risposta di creazione sessione si chiama `url` (vedi lo [schema OpenAPI di Create Session](https://docs.didit.me/it/sessions-api/create-session.md)). Passalo direttamente a `startVerification({ url })`.***## Configurazione| Opzione | Tipo | Predefinito | Descrizione |
| - | - | - | - |
| `loggingEnabled` | `boolean` | `false` | Abilita il logging dell'SDK per il debug |
| `containerElement` | `HTMLElement` | `document.body` | Elemento contenitore personalizzato in cui montare la modale |
| `zIndex` | `number` | `9999` | Z-index dell'overlay modale |
| `showCloseButton` | `boolean` | `true` | Mostra il pulsante di chiusura sulla modale |
| `showExitConfirmation` | `boolean` | `true` | Mostra la finestra di conferma all'uscita quando si chiude |
| `closeModalOnComplete` | `boolean` | `false` | Chiude automaticamente la modale al termine della verifica |
| `embedded` | `boolean` | `false` | Mostra la verifica inline invece che in un overlay modale |
| `embeddedContainerId` | `string` | — | ID dell'elemento contenitore per la modalità inline (obbligatorio quando `embedded` è `true`) |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Fotocamera con cui si apre per prima l'acquisizione del documento. Vedi [Opzioni della fotocamera](#opzioni-della-fotocamera) |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Fotocamera con cui si apre per prima l'acquisizione del volto (rilevamento della vitalità). Vedi [Opzioni della fotocamera](#opzioni-della-fotocamera) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Mostra il selettore della fotocamera durante l'acquisizione nel passaggio del documento |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Mostra il selettore della fotocamera durante l'acquisizione nel passaggio del rilevamento della vitalità |> [!TIP]
>
> Consulta le [definizioni complete dei tipi TypeScript](#tipi-typescript) più sotto per l'interfaccia completa `DiditSdkConfiguration`.***## Opzioni della fotocamera> [!NOTE]
>
> Le opzioni della fotocamera richiedono `@didit-protocol/sdk-web`**0.4.0** o successiva.L'SDK web espone le stesse quattro opzioni della fotocamera degli [SDK nativi](https://docs.didit.me/it/integration/native-sdks/overview.md). Per impostazione predefinita, l'acquisizione del documento apre la fotocamera posteriore e l'acquisizione del volto (vitalità) apre la fotocamera anteriore (selfie), e in entrambi i passaggi è disponibile un selettore di fotocamera durante l'acquisizione sui dispositivi con più di una fotocamera. Imposta `defaultLivenessCamera: 'back'` per aprire l'acquisizione del volto con la fotocamera posteriore, ad esempio in un chiosco o quando un operatore tiene il dispositivo e lo punta verso la persona da verificare.| Opzione | Tipo | Predefinito | Descrizione |
| - | - | - | - |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Obiettivo utilizzato alla prima apertura della schermata di acquisizione del documento |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Obiettivo utilizzato alla prima apertura della schermata di acquisizione della vitalità (volto passivo) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Mostra il selettore di fotocamera durante l'acquisizione nella schermata del documento; `false` blocca l'utente su `defaultDocumentCamera` |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Mostra il selettore di fotocamera durante l'acquisizione nella schermata di vitalità; `false` blocca l'utente su `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
  }
});
```- I valori accettati per l'obiettivo sono `'front'` e `'back'`. Qualsiasi altro valore viene ignorato, così come un flag del selettore che non è un booleano.
- Un dispositivo privo della fotocamera richiesta mantiene quella che ha: un laptop a cui viene richiesta `'back'` usa comunque la webcam. Il selettore è nascosto sui dispositivi con una sola fotocamera, indipendentemente dai flag.
- Le opzioni di rilevamento della vitalità si applicano al controllo passivo della vitalità. Il rilevamento attivo della vitalità non è influenzato.
- L'SDK inoltra le opzioni alla pagina di verifica come parametri di query dell'URL di verifica: `document_camera`, `liveness_camera`, `document_camera_switch` e `liveness_camera_switch`. Se apri direttamente l'URL di verifica invece di passare dall'SDK, impostali tu: aggiungi `?liveness_camera=back` a un URL senza stringa di query, `&liveness_camera=back` a un URL che ha già dei parametri, oppure impostali con l'API `URL`, che gestisce entrambi i casi:```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());
```***## Invio di eventi`DiditSdk.shared.submitEvent()` mette in coda gli eventi dell'utente finale (registrazione, accesso, accesso non riuscito, disconnessione, reimpostazione della password, MFA, cambio di dispositivo) per il monitoraggio degli eventi di Didit.
Il tuo backend genera un token di monitoraggio per la persona, e l'SDK invia gli eventi in batch insieme all'impronta del dispositivo.
Non inviare mai una chiave API al browser.```typescript theme={null}
DiditSdk.shared.submitEvent({
  monitoringToken, // minted by your backend for this person
  event: { category: "auth", actionType: "login", payload: { method: "password" } },
});
```Consulta [Invio di eventi tramite SDK](https://docs.didit.me/it/transaction-monitoring/sdk-event-submission.md) per il token, i campi degli eventi e il comportamento di consegna.***## Dimensionamento e scorrimento della modale> [!NOTE]
>
> Il comportamento di dimensionamento descritto qui richiede la versione **0.3.1** o successiva. Le versioni **0.3.0** e precedenti possono tagliare il flusso di verifica su viewport desktop e in orientamento orizzontale di altezza ridotta.La modalità modale usa una larghezza massima di 500px e un'altezza massima di 700px. Su entrambi i viewport, desktop e in orientamento orizzontale, quando hanno altezza ridotta, l'iframe occupa il 90% della viewport visibile. Il flusso di verifica scorre all'interno dell'iframe, così ogni passaggio resta raggiungibile mentre la pagina sotto la modale rimane bloccata.L'SDK usa `dvh` sui browser che supportano le unità di viewport dinamiche e ricorre a `vh` sui browser meno recenti supportati. Con larghezze di 540px o inferiori, la modale occupa l'intera viewport visibile. Il pulsante di chiusura e la conferma di uscita restano all'interno della modale.### Flusso di verifica ridisegnato> [!NOTE]
>
> Tutto il contenuto di questa sezione si applica dalla versione **0.5.0**, che non è ancora stata pubblicata. Finché non esegui l'aggiornamento, la modale mantiene le dimensioni descritte sopra.Dalla versione 0.5.0, la modale si dimensiona in base al flusso di verifica ridisegnato, una volta che la pagina comunica il proprio layout con un [messaggio `didit:layout`](https://docs.didit.me/it/integration/web-sdks/incontext-iframe#dimensiona-l’iframe-da-diditlayout):| Larghezza della finestra | Modale (dalla versione 0.5.0) |
| - | - |
| 1024px o più | 960px per 660px in ogni passaggio, al massimo il 90% della larghezza e dell'altezza della finestra |
| da 541px a 1023px | 500px di larghezza e alta quanto il contenuto della pagina, al massimo il 90% dell'altezza della finestra |
| 540px o meno | Schermo intero |- **Dimensione iniziale, dalla versione 0.5.0:** finché la pagina non comunica il proprio layout, e per le pagine che non lo fanno mai, la modale mantiene la dimensione massima esistente di 500px per 700px. Continua ad adattarsi alle finestre di altezza ridotta e resta a schermo intero a 540px o meno.
- **Pulsante di chiusura, dalla versione 0.5.0:** un cerchio di 44px sovrapposto alla barra superiore della pagina. Segue il tema chiaro o scuro della pagina e si sposta a sinistra nelle lingue da destra a sinistra.
- **Modalità incorporata, dalla versione 0.5.0:** continua a riempire il proprio elemento host, come prima (vedi [Modalità incorporata](#modalità-incorporata)).
- **URL di verifica, dalla versione 0.5.0:** l'SDK aggiunge `sdk_presentation` (`modal` o `embedded`) e, in una modale, `sdk_close_button` (`true` o `false`, in base a `showCloseButton`), così la pagina sa come viene mostrata.
- **Eventi, dalla versione 0.5.0:** l'SDK gestisce `didit:layout` da solo e non lo passa a `onEvent`.Non c'è nulla da configurare, e tutte le opzioni esistenti continuano a funzionare.***## Modalità incorporataLa modalità incorporata non usa il limite di 500px per 700px della modale. L'SDK riempie il riquadro del contenuto dell'elemento host, quindi assegna a quell'elemento un'altezza esplicita o comunque risolta:```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'
  }
});
```Se l'host non ha un'altezza risolta, anche l'iframe incorporato non ha un'altezza utilizzabile. Ridimensiona l'host quando cambia il layout; l'SDK continua a riempirlo automaticamente.***## Risultati della verificaL'SDK restituisce tre tipi di risultato:### CompletatoIl flusso di verifica è terminato (approvato, in attesa o rifiutato).```typescript theme={null}
{
  type: 'completed',
  session: {
    sessionId: 'session-uuid',
    status: 'Approved' | 'Pending' | 'Declined'
  }
}
```> [!NOTE]
>
> Il tipo TypeScript dichiara `'Approved' | 'Pending' | 'Declined'`, ma il valore viene passato dallo stato della sessione del flusso ospitato: potresti ricevere anche altri stati, come `In Review`. `Pending` è il valore di ripiego dell'SDK quando il flusso non ha riportato alcuno stato. Tratta `status` come un'indicazione e affidati al [webhook](https://docs.didit.me/it/integration/webhooks.md) per la decisione definitiva.### AnnullatoL'utente ha chiuso la modale di verifica. `session` è incluso quando un `sessionId` era già noto (può essere `undefined` se l'utente ha annullato prima che l'iframe ne riportasse uno).```typescript theme={null}
{
  type: 'cancelled',
  session: {
    sessionId: 'session-uuid',
    status: 'Pending'
  }
}
```### Non riuscitoSi è verificato un errore durante la verifica.```typescript theme={null}
{
  type: 'failed',
  error: {
    type: 'sessionExpired' | 'networkError' | 'cameraAccessDenied' | 'unknown',
    message: 'Your verification session has expired.'
  }
}
```***## Gestione dello statoPuoi osservare lo stato dell'SDK per creare un'interfaccia personalizzata:```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);
```***## Riferimento API### DiditSdk.sharedL'istanza singleton dell'SDK.### Metodi| Metodo | Descrizione |
| - | - |
| `startVerification(options)` | Avvia il flusso di verifica |
| `submitEvent(options)` | Mette in coda un evento dell'utente finale per il monitoraggio degli eventi con un token di monitoraggio |
| `close()` | Chiude a livello programmatico la modale di verifica |
| `destroy()` | Distrugge l'istanza dell'SDK ed esegue la pulizia |### Proprietà| Proprietà | Tipo | Descrizione |
| - | - | - |
| `state` | `DiditSdkState` | Stato corrente dell'SDK |
| `configuration` | `DiditSdkConfiguration \| undefined` | Configurazione attiva (impostata mentre una verifica è in corso) |
| `isPresented` | `boolean` | Indica se la modale di verifica è aperta |
| `errorMessage` | `string \| undefined` | Messaggio di errore (impostato quando lo stato è `error`); un avvio non riuscito resta in `error` finché non avvii di nuovo |### Callback| Callback | Parametri | Descrizione |
| - | - | - |
| `onComplete` | `(result: VerificationResult)` | Chiamato al termine della verifica |
| `onStateChange` | `(state: DiditSdkState, error?: string)` | Chiamato a ogni cambiamento di stato |
| `onEvent` | `(event: VerificationEvent)` | Chiamato per gli eventi granulari di verifica |***## Eventi granulariMonitora l'avanzamento della verifica con il callback `onEvent`:```typescript theme={null}
DiditSdk.shared.onEvent = (event) => {
  console.log('Event:', event.type, event.data);
};
```### Riferimento agli eventi| Evento | Descrizione | Payload dei dati |
| - | - | - |
| `didit:ready` | La pagina è pronta e il sessionId è disponibile | `{ sessionId }` |
| `didit:started` | L'utente ha avviato la verifica | `{ sessionId? }` |
| `didit:step_started` | È iniziato un passaggio della verifica | `{ step, sessionId? }` |
| `didit:step_completed` | Un passaggio è stato completato con successo | `{ step, nextStep?, sessionId? }` |
| `didit:step_changed` | Il passaggio corrente è cambiato | `{ step, previousStep?, sessionId? }` |
| `didit:media_started` | È iniziata l'acquisizione dalla fotocamera o di contenuti multimediali | `{ step, mediaType }` |
| `didit:media_captured` | Foto o video acquisiti | `{ step, isAuto }` |
| `didit:document_selected` | L'utente ha selezionato il tipo di documento e il paese | `{ documentType, country }` |
| `didit:verification_submitted` | I dati sono stati inviati per l'elaborazione | `{ step, sessionId? }` |
| `didit:code_sent` | Codice OTP inviato | `{ step, channel?, codeSize?, sessionId? }` |
| `didit:code_verified` | Codice OTP verificato | `{ step, sessionId? }` |
| `didit:status_updated` | Lo stato della sessione è cambiato | `{ status, previousStep?, sessionId? }` |
| `didit:completed` | Il flusso di verifica è stato completato | `{ sessionId?, status?, country?, documentType? }` |
| `didit:cancelled` | L'utente ha annullato la verifica | `{ sessionId? }` |
| `didit:error` | Si è verificato un errore | `{ error: string, step?, sessionId? }` |
| `didit:close_request` | L'utente ha chiesto di chiudere la modale | (nessun dato) |### Connessione persaSe la connessione dell'utente cade, la pagina di verifica sovrappone al flusso una schermata «Nessuna connessione internet» invece di lasciare un passaggio in caricamento.
La pagina continua a controllare in background e chiude da sola la schermata appena Didit torna raggiungibile, e l'utente prosegue dal passaggio in cui si trovava.
All'interno della modale o di un iframe dell'SDK, la schermata offre anche **Exit Verification**: in quel caso la pagina invia `didit:error` con `error: "network_error"`, seguito da `didit:cancelled`, e l'SDK chiude la modale e chiama `onComplete` con `type: "cancelled"`.A partire dalla versione 0.5.0, il messaggio `didit:layout` della pagina dimensiona la modale e non raggiunge `onEvent`. Se invece incorpori la pagina con un tuo iframe, consulta [Dimensionare l'iframe da `didit:layout`](https://docs.didit.me/it/integration/web-sdks/incontext-iframe#dimensiona-l’iframe-da-diditlayout).### Valori di passaggioIl campo `step` può assumere uno dei seguenti valori:- `document_selection` - Selezione del tipo di documento
- `document_front` - Lato anteriore del documento
- `document_back` - Lato posteriore del documento
- `face` - Verifica del volto e della vitalità
- `email` - Verifica email
- `phone` - Verifica telefonica
- `poa` - Prova di residenza
- `questionnaire` - Passaggio del questionario### Valori di canaleIl campo `channel` in `code_sent` può essere:- `email` - Codice inviato via email
- `sms` - Codice inviato via SMS
- `whatsapp` - Codice inviato via WhatsApp### Dimensione del codiceIl campo `codeSize` in `code_sent` indica la lunghezza del codice OTP (ad esempio 4 o 6 cifre).***## Tipi 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.