Verifica dell'identità in iframe: KYC web integrato

Integra il flusso di verifica Didit direttamente nella tua applicazione tramite un iframe. Così offri un’esperienza fluida, senza reindirizzare gli utenti fuori dal tuo sito.

Panoramica

Funzionalità	UniLink (senza backend)	Sessione API (con backend)
Tempo di configurazione	< 1 minuto	5-10 minuti
Backend richiesto	❌ No	✅ Sì
`vendor_data` personalizzato	❌ No	✅ Sì
`metadata` personalizzati	❌ No	✅ Sì
Callback per sessione	❌ No	✅ Sì
Tracciamento delle sessioni	❌ No	✅ Sì

Iframe UniLink (senza backend)

Il modo più rapido per iniziare: copia e incolla il tuo URL UniLink.

Cosa ti serve

Un workflow Didit (creato nella Didit Console)
Il tuo URL UniLink (clicca su Copy Link nel tuo workflow)

Implementazione

<iframe 
  src="https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64"
  style="width: 100%; height: 700px; border: none;" 
  allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
></iframe>

⚠️ Obbligatorio: l’attributo allow è obbligatorio per l’accesso alla fotocamera durante il rilevamento della vitalità.

Vantaggi principali

Configurazione in meno di 1 minuto: nessun backend, nessuna chiave API
Nessuna configurazione: l’URL di callback si imposta nelle impostazioni del workflow
Ideale per gli MVP: inizi subito

Iframe con sessione API (con backend)

Per integrazioni avanzate che richiedono una personalizzazione per sessione.

Quando usarlo

Passa vendor_data o metadata personalizzati per sessione
Imposta URL di callback diversi per sessione
Traccia le sessioni lato server prima dell’avvio della verifica
Associa le sessioni agli ID utente

Implementazione

Passaggio 1: crea una sessione (backend) La risposta della creazione della sessione usa un campo chiamato url: usalo come src dell’iframe.

// Node.js / Express
app.post('/api/create-verification', async (req, res) => {
  const { userId } = req.body;

  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: userId,
      callback: 'https://yourapp.com/verification-callback',
      metadata: { source: 'web-app', timestamp: Date.now() },
    }),
  });

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

  // 201 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({ sessionId: session.session_id, verificationUrl: session.url });
});

Passaggio 2: inserisci nell’iframe (frontend)

<iframe 
  id="didit-verification"
  src="" <!-- Set dynamically from API response -->
  style="width: 100%; height: 650px; border: none;" 
  allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
></iframe>

<script>
  async function startVerification() {
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    document.getElementById('didit-verification').src = verificationUrl;
  }
</script>

Ascoltare gli eventi (postMessage)

La pagina di verifica invia eventi alla finestra padre. Ogni messaggio ha questa struttura:

{
  type: 'didit:<event>',   // e.g. 'didit:completed'
  data: { /* payload */ }, // event-specific; may be undefined
  timestamp: 1718000000000 // ms epoch
}

Il payload è annidato: leggi event.data.data.sessionId, non event.data.sessionId:

window.addEventListener('message', (event) => {
  // Use your white-label domain here if you have one configured
  if (event.origin !== 'https://verify.didit.me') return;

  const { type, data } = event.data || {};

  if (type === 'didit:ready') {
    console.log('Session ID:', data.sessionId); // available as soon as the page loads
  }
  if (type === 'didit:completed') {
    console.log('Done:', data.sessionId, data.status); // e.g. "Approved" | "Declined" | "In Review"
    // UI hint only — the canonical decision arrives on your backend via webhook
  }
});

Eventi principali: didit:ready ({ sessionId }), didit:started, didit:step_started / didit:step_completed / didit:step_changed ({ step, ... }), didit:status_updated ({ status }), didit:completed ({ sessionId, status }), didit:cancelled, didit:error ({ error, step? }), didit:close_request, e didit:layout ({ contentHeight, colorScheme, dir }, vedi sotto). Il riferimento degli eventi dell’SDK JavaScript elenca gli eventi di verifica disponibili come callback tipizzati. A partire dalla versione 0.5.0, l’SDK gestisce internamente i messaggi di layout invece di inoltrarli a onEvent.

Dimensiona l’iframe da `didit:layout`

La pagina di verifica indica lo spazio di cui ha bisogno con un messaggio didit:layout. Ne invia uno al caricamento e un altro ogni volta che cambiano l’altezza del contenuto, il tema o la direzione del testo:

{
  type: 'didit:layout',
  data: {
    contentHeight: 612,    // CSS px
    colorScheme: 'light',  // 'light' | 'dark'
    dir: 'ltr'             // 'ltr' | 'rtl'
  },
  timestamp: 1718000000000
}

Campo	Tipo	Descrizione
`contentHeight`	`number`	L’altezza naturale del contenuto della pagina in pixel CSS, barra superiore inclusa
`colorScheme`	`'light' \| 'dark'`	Il tema con cui viene mostrata la pagina. Con i colori White label, lo decide il colore di sfondo impostato da te, non l’impostazione del dispositivo
`dir`	`'ltr' \| 'rtl'`	La direzione del testo della lingua della pagina

Per ricevere didit:layout nel tuo iframe, aggiungi sdk_presentation=embedded all’URL di verifica. A partire dalla versione 0.5.0, l’SDK JavaScript imposta la presentazione per te. Senza un parametro di presentazione, la pagina usa il layout autonomo e non invia messaggi di layout.

Questo host segue le dimensioni consigliate: una card fissa a partire da una larghezza di 1024px, a schermo intero fino a 540px e sotto, e, nel mezzo, un iframe largo 500px che assume l’altezza comunicata dalla pagina:

<iframe
  id="didit-verification"
  class="didit-iframe"
  title="Didit verification"
  allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
></iframe>

<style>
  /* 541px to 1023px wide: 500px wide and as tall as the content */
  .didit-iframe {
    display: block;
    width: 500px;
    max-width: 100%;
    height: var(--didit-content-height, 700px); /* 700px until the first didit:layout */
    max-height: 90vh;
    max-height: 90dvh;
    margin: 0 auto;
    border: none;
    border-radius: 16px;
  }

  /* 1024px and wider: the computer card */
  @media (min-width: 1024px) {
    .didit-iframe {
      width: 960px;
      max-width: 90vw;
      height: 660px;
    }
  }

  /* 540px and below: full screen */
  @media (max-width: 540px) {
    .didit-iframe {
      position: fixed;
      inset: 0;
      width: 100%;
      height: 100vh;
      height: 100dvh;
      max-height: none;
      border-radius: 0;
    }
  }
</style>

<script>
  const DIDIT_ORIGIN = 'https://verify.didit.me'; // or your white-label domain
  const iframe = document.getElementById('didit-verification');

  // verificationUrl: the session `url` from your backend, or your UniLink
  const src = new URL(verificationUrl);
  src.searchParams.set('sdk_presentation', 'embedded');
  window.addEventListener('message', (event) => {
    if (event.origin !== DIDIT_ORIGIN || event.source !== iframe.contentWindow) return;
    const { type, data } = event.data || {};
    if (type !== 'didit:layout') return;
    const height = data?.contentHeight;
    if (typeof height !== 'number' || !Number.isFinite(height) || height <= 0) return;

    // Only the 541px to 1023px size reads it; the other two sizes are fixed
    iframe.style.setProperty('--didit-content-height', `${height}px`);
  });
  iframe.src = src.toString();
</script>

Tra 541px e 1023px, questo esempio usa un’altezza iniziale di 700px finché non arriva un messaggio di layout, con un massimo del 90% dell’altezza visibile della finestra. Le dimensioni per computer e telefono si applicano subito. Sui telefoni l’iframe copre la finestra, quindi prevedi nel tuo host un modo per uscire dalla verifica. Usa colorScheme e dir per adattare i controlli che disegni attorno all’iframe al tema e alla direzione del testo della pagina. Se la connessione dell’utente cade, la pagina mostra una schermata “Nessuna connessione a internet” che si chiude da sola quando la connessione torna disponibile. Se l’utente sceglie Exit Verification in quella schermata, la pagina invia didit:error con error: "network_error", poi didit:cancelled: chiudi l’iframe alla ricezione di didit:cancelled.

Implementazione modale

Per un’esperienza modale curata che si sovrappone alla tua pagina:

HTML/CSS/JS

<!DOCTYPE html>
<html>
<head>
  <style>
    .didit-modal-overlay {
      display: none;
      position: fixed;
      inset: 0;
      background: rgba(0, 0, 0, 0.6);
      z-index: 9999;
      backdrop-filter: blur(4px);
    }
    
    .didit-modal-container {
      position: absolute;
      top: 50%;
      left: 50%;
      transform: translate(-50%, -50%);
      width: 90%;
      max-width: 480px;
      height: 85vh;
      max-height: 750px;
      background: white;
      border-radius: 16px;
      overflow: hidden;
      box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
    }
    
    .didit-modal-close {
      position: absolute;
      top: 12px;
      right: 12px;
      z-index: 10;
      width: 32px;
      height: 32px;
      border: none;
      background: rgba(0, 0, 0, 0.1);
      border-radius: 50%;
      cursor: pointer;
      font-size: 18px;
      display: flex;
      align-items: center;
      justify-content: center;
    }
    
    .didit-modal-close:hover {
      background: rgba(0, 0, 0, 0.2);
    }
    
    .didit-iframe {
      width: 100%;
      height: 100%;
      border: none;
    }
  </style>
</head>
<body>
  <button onclick="openVerification()">Verify Identity</button>

  <div id="didit-modal" class="didit-modal-overlay">
    <div class="didit-modal-container">
      <button class="didit-modal-close" onclick="closeVerification()">✕</button>
      <iframe 
        id="didit-iframe"
        class="didit-iframe"
        allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
      ></iframe>
    </div>
  </div>

  <script>
    const UNILINK_URL = 'https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64';
    
    function openVerification() {
      document.getElementById('didit-iframe').src = UNILINK_URL;
      document.getElementById('didit-modal').style.display = 'block';
      document.body.style.overflow = 'hidden';
    }
    
    function closeVerification() {
      document.getElementById('didit-iframe').src = '';
      document.getElementById('didit-modal').style.display = 'none';
      document.body.style.overflow = '';
    }
    
    // Close on escape key
    document.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') closeVerification();
    });
    
    // Close on overlay click
    document.getElementById('didit-modal').addEventListener('click', (e) => {
      if (e.target.id === 'didit-modal') closeVerification();
    });
  </script>
</body>
</html>

Componente React

Un componente React riutilizzabile per la verifica in modale:

import { useState, useEffect } from 'react';

interface DiditInContextProps {
  /**
   * Either the `url` returned by POST /v3/session/ (API session)
   * or your UniLink URL copied from the Console (Workflows → Copy Link).
   * Don't derive the UniLink yourself — the path segment is a 22-character
   * base64url encoding of the workflow UUID's raw bytes, not btoa(workflowId).
   */
  verificationUrl: string;
  isOpen: boolean;
  onClose: () => void;
  onComplete?: (sessionId: string, status: string) => void;
}

export function DiditInContext({ 
  verificationUrl, 
  isOpen, 
  onClose,
  onComplete 
}: DiditInContextProps) {
  const [iframeSrc, setIframeSrc] = useState<string>('');

  useEffect(() => {
    if (isOpen) {
      setIframeSrc(verificationUrl);
      document.body.style.overflow = 'hidden';
    } else {
      setIframeSrc('');
      document.body.style.overflow = '';
    }
  }, [isOpen, verificationUrl]);

  // Listen for postMessage from iframe
  // Messages look like: { type: 'didit:<event>', data: {...}, timestamp }
  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      // Use your white-label domain here if you have one configured
      if (event.origin !== 'https://verify.didit.me') return;

      if (event.data?.type === 'didit:completed' && onComplete) {
        onComplete(event.data.data?.sessionId, event.data.data?.status);
        onClose();
      }
    };

    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, [onComplete, onClose]);

  // Handle escape key
  useEffect(() => {
    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === 'Escape' && isOpen) onClose();
    };
    
    document.addEventListener('keydown', handleEscape);
    return () => document.removeEventListener('keydown', handleEscape);
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return (
    <div 
      className="fixed inset-0 bg-black/60 backdrop-blur-sm z-50 flex items-center justify-center"
      onClick={(e) => e.target === e.currentTarget && onClose()}
    >
      <div className="relative w-[90%] max-w-[480px] h-[85vh] max-h-[750px] bg-white rounded-2xl overflow-hidden shadow-2xl">
        <button 
          onClick={onClose}
          className="absolute top-3 right-3 z-10 w-8 h-8 rounded-full bg-black/10 hover:bg-black/20 flex items-center justify-center"
          aria-label="Close"
        >
          ✕
        </button>
        <iframe 
          src={iframeSrc}
          className="w-full h-full border-0"
          allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
          title="Didit Verification"
        />
      </div>
    </div>
  );
}

Utilizzo

import { useState } from 'react';
import { DiditInContext } from './DiditInContext';

function App() {
  const [isVerificationOpen, setIsVerificationOpen] = useState(false);
  
  return (
    <>
      <button onClick={() => setIsVerificationOpen(true)}>
        Verify Identity
      </button>
      
      <DiditInContext
        verificationUrl="https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64" // UniLink from Console, or the API session `url`
        isOpen={isVerificationOpen}
        onClose={() => setIsVerificationOpen(false)}
        onComplete={(sessionId, status) => {
          console.log(`Verification ${status}: ${sessionId}`);
          if (status === 'Approved') {
            // Navigate to success page
          }
        }}
      />
    </>
  );
}

Componente Vue

<template>
  <Teleport to="body">
    <div 
      v-if="isOpen"
      class="fixed inset-0 bg-black/60 backdrop-blur-sm z-50 flex items-center justify-center"
      @click.self="$emit('close')"
    >
      <div class="relative w-[90%] max-w-[480px] h-[85vh] max-h-[750px] bg-white rounded-2xl overflow-hidden shadow-2xl">
        <button 
          @click="$emit('close')"
          class="absolute top-3 right-3 z-10 w-8 h-8 rounded-full bg-black/10 hover:bg-black/20 flex items-center justify-center"
        >
          ✕
        </button>
        <iframe 
          :src="iframeSrc"
          class="w-full h-full border-0"
          allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
        />
      </div>
    </div>
  </Teleport>
</template>

<script setup lang="ts">
import { computed, watch, onMounted, onUnmounted } from 'vue';

const props = defineProps<{
  isOpen: boolean;
  // The `url` from POST /v3/session/, or your UniLink URL copied from the
  // Console (Workflows → Copy Link). Don't derive the UniLink with btoa() —
  // its path segment is base64url of the workflow UUID's raw bytes.
  verificationUrl: string;
}>();

const emit = defineEmits<{
  close: [];
  complete: [sessionId: string, status: string];
}>();

const iframeSrc = computed(() => (props.isOpen ? props.verificationUrl : ''));

// Handle escape key
const handleEscape = (e: KeyboardEvent) => {
  if (e.key === 'Escape' && props.isOpen) emit('close');
};

// Handle postMessage — messages look like { type: 'didit:<event>', data: {...}, timestamp }
const handleMessage = (event: MessageEvent) => {
  // Use your white-label domain here if you have one configured
  if (event.origin !== 'https://verify.didit.me') return;
  if (event.data?.type === 'didit:completed') {
    emit('complete', event.data.data?.sessionId, event.data.data?.status);
  }
};

onMounted(() => {
  document.addEventListener('keydown', handleEscape);
  window.addEventListener('message', handleMessage);
});

onUnmounted(() => {
  document.removeEventListener('keydown', handleEscape);
  window.removeEventListener('message', handleMessage);
});

// Lock body scroll when open
watch(() => props.isOpen, (isOpen) => {
  document.body.style.overflow = isOpen ? 'hidden' : '';
});
</script>

Configurazione

Autorizzazioni richieste

Usa questo elenco completo di autorizzazioni per l’acquisizione, la posizione, la copia e la compatibilità dei contenuti multimediali:

allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"

Autorizzazione	Utilizzo e cosa succede senza di essa
`camera`	Scansione del documento e acquisizione del volto. Senza di essa, la fotocamera non può avviarsi e l’utente visualizza indicazioni per l’accesso alla fotocamera
`microphone`	Audio facoltativo durante la registrazione video del documento e del volto. Senza di essa, l’acquisizione prosegue senza audio
`geolocation`	Il passaggio relativo alla posizione rileva la posizione del dispositivo. Senza di essa, l’utente vede Location access is off, anche se ha consentito l’accesso alla posizione nel browser
`clipboard-write`	Copia del riferimento della sessione o del link di verifica, anche nella schermata del browser in-app. Senza di essa, l’azione di copia può fallire e l’utente deve copiare manualmente il testo visibile o l’indirizzo del browser
`fullscreen`	Consente ai controlli multimediali di richiedere la modalità a schermo intero. Senza di essa, tali controlli restano all’interno dell’iframe
`autoplay`	Consente la riproduzione automatica dei video informativi e delle anteprime della fotocamera, nel rispetto delle regole del browser. Senza di essa, la riproduzione può attendere un’azione dell’utente
`encrypted-media`	Mantenuta per la compatibilità con i contenuti multimediali protetti. I passaggi di acquisizione attuali non la richiedono; senza di essa, la riproduzione di contenuti protetti verrebbe bloccata
`digital-credentials-get`	Condivisione di un documento d’identità digitale da un wallet, come Google Wallet, tramite la Digital Credentials API del browser. Senza di essa, il browser rifiuta la richiesta al wallet all’interno del tuo iframe, quindi l’utente non può condividere un documento dal wallet in quel punto

L’attributo allow delega le autorizzazioni; non sostituisce la scelta dell’utente né un’intestazione Permissions-Policy più restrittiva sulla tua pagina host.

Dimensioni dell’iframe

Il flusso di verifica si adatta automaticamente alle dimensioni del proprio iframe. Dimensiona l’iframe in base alla finestra in cui viene mostrato:

Larghezza della finestra	Dimensioni consigliate dell’iframe
1024px o più (computer)	960px per 660px, al massimo il 90% della larghezza e dell’altezza della finestra. Mantieni queste dimensioni in ogni passaggio
da 541px a 1023px	500px di larghezza e altezza pari al contenuto: ricava l’altezza dal `contentHeight` del messaggio `didit:layout`, al massimo il 90% dell’altezza della finestra
540px o meno (telefono)	Schermo intero: la larghezza completa e l’altezza visibile completa della finestra, senza angoli arrotondati

Per l’intervallo intermedio, parti da 500px per 700px finché non arriva il primo messaggio didit:layout, con lo stesso limite di altezza. L’esempio di didit:layout applica tutte e tre le dimensioni, comprese quelle per computer e telefono, prima che arrivi qualsiasi messaggio.

Content Security Policy (CSP)

Se usi CSP, aggiungi Didit alla direttiva frame-src:

Content-Security-Policy: frame-src https://verify.didit.me;

Verifica tra dispositivi

L’iframe InContext supporta automaticamente la verifica tra dispositivi:

L’utente avvia la verifica su desktop
Se la fotocamera non è disponibile, viene mostrato un codice QR
L’utente scansiona il codice QR con il telefono
L’utente completa la verifica sul telefono
L’iframe desktop si aggiorna automaticamente con il risultato

Questo avviene automaticamente, senza alcuna configurazione aggiuntiva.

Risoluzione dei problemi

La fotocamera non funziona

Assicurati che l’iframe includa l’elenco completo delle autorizzazioni
Verifica che il sito sia servito tramite HTTPS
Controlla che l’utente abbia concesso le autorizzazioni della fotocamera al tuo dominio
Prova il metodo Redirect se l’accesso alla fotocamera nell’iframe non funziona

L’iframe non si carica

Controlla eventuali problemi di Content Security Policy (CSP)
Aggiungi https://verify.didit.me alla direttiva frame-src
Controlla la console del browser per eventuali errori

postMessage non ricevuto

Verifica di essere in ascolto sull’origine corretta (https://verify.didit.me, oppure il tuo dominio white label)
Controlla che il listener dell’evento sia aggiunto prima di aprire l’iframe
Controlla il nome e la struttura dell’evento: i tipi hanno il prefisso (didit:completed, non verification_complete) e il payload è annidato in event.data.data

Repository di esempio

Repository GitHub

Visualizza il codice sorgente e gli esempi su GitHub

Guide

Autenticazione

Model Context Protocol (MCP)

SDK web

SDK nativi

SDK server

Integrazioni

Verifica dell'identità in iframe: KYC web integrato

Panoramica

Iframe UniLink (senza backend)

Cosa ti serve

Implementazione

Vantaggi principali

Iframe con sessione API (con backend)

Quando usarlo

Implementazione

Ascoltare gli eventi (postMessage)

Dimensiona l’iframe da `didit:layout`

Implementazione modale

HTML/CSS/JS

Componente React

Utilizzo

Componente Vue

Configurazione

Autorizzazioni richieste

Dimensioni dell’iframe

Content Security Policy (CSP)

Verifica tra dispositivi

Risoluzione dei problemi

La fotocamera non funziona

L’iframe non si carica

postMessage non ricevuto

Repository di esempio

Repository GitHub

​Panoramica

​Iframe UniLink (senza backend)

​Cosa ti serve

​Implementazione

​Vantaggi principali

​Iframe con sessione API (con backend)

​Quando usarlo

​Implementazione

​Ascoltare gli eventi (postMessage)

​Dimensiona l’iframe da didit:layout

​Implementazione modale

​HTML/CSS/JS

​Componente React

​Utilizzo

​Componente Vue

​Configurazione

​Autorizzazioni richieste

​Dimensioni dell’iframe

​Content Security Policy (CSP)

​Verifica tra dispositivi

​Risoluzione dei problemi

​La fotocamera non funziona

​L’iframe non si carica

​postMessage non ricevuto

​Repository di esempio

Repository GitHub

Panoramica

Iframe UniLink (senza backend)

Cosa ti serve

Implementazione

Vantaggi principali

Iframe con sessione API (con backend)

Quando usarlo

Implementazione

Ascoltare gli eventi (postMessage)

Dimensiona l’iframe da `didit:layout`

Implementazione modale

HTML/CSS/JS

Componente React

Utilizzo

Componente Vue

Configurazione

Autorizzazioni richieste

Dimensioni dell’iframe

Content Security Policy (CSP)

Verifica tra dispositivi

Risoluzione dei problemi

La fotocamera non funziona

L’iframe non si carica

postMessage non ricevuto

Repository di esempio