Verificació d'identitat amb iframe: KYC web integrat

Incrusta el flux de verificació de Didit directament a la teva aplicació amb un iframe. Així s’ofereix una experiència fluida sense redirigir els usuaris fora del teu lloc web.

Visió general

Funcionalitat	UniLink (sense backend)	Sessió d’API (amb backend)
Temps de configuració	< 1 minut	5-10 minuts
Backend necessari	❌ No	✅ Sí
`vendor_data` personalitzat	❌ No	✅ Sí
`metadata` personalitzat	❌ No	✅ Sí
Callback per sessió	❌ No	✅ Sí
Seguiment de sessions	❌ No	✅ Sí

Iframe amb UniLink (sense backend)

La manera més ràpida de començar: només cal copiar i enganxar la teva URL d’UniLink.

Què necessites

Un flux de treball de Didit (creat a la Consola de Didit)
La teva URL d’UniLink (fes clic a Copy Link al teu flux de treball)

Implementació

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

⚠️ Obligatori: l’atribut allow és obligatori per poder accedir a la càmera durant la prova de vida.

Beneficis principals

Configuració en menys d’1 minut: sense backend ni claus d’API
Cap configuració: la URL de callback es defineix a la configuració del flux de treball
Ideal per a MVP: comença de seguida

Iframe amb sessió d’API (amb backend)

Per a integracions avançades que necessiten personalització per sessió.

Quan utilitzar-lo

Passar vendor_data o metadata personalitzats per sessió
Definir URLs de callback diferents per sessió
Fer el seguiment de sessions al servidor abans que comenci la verificació
Associar sessions amb els identificadors dels teus usuaris

Implementació

Pas 1: crea una sessió (backend) La resposta de creació de sessió conté un camp anomenat url: utilitza’l com a src de l’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 });
});

Pas 2: incrusta l’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>

Escoltar esdeveniments (postMessage)

La pàgina de verificació envia esdeveniments a la finestra pare. Cada missatge té aquesta estructura:

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

El payload és imbricat: llegeix event.data.data.sessionId, no 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
  }
});

Esdeveniments clau: 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 i didit:layout ({ contentHeight, colorScheme, dir }, vegeu a continuació). La referència d’esdeveniments del SDK de JavaScript enumera els esdeveniments de verificació disponibles com a callbacks tipats. A partir de la versió 0.5.0, el SDK gestiona internament els missatges de disposició en lloc de reenviar-los a onEvent.

Ajusta la mida de l’iframe amb `didit:layout`

La pàgina de verificació indica quin espai necessita amb un missatge didit:layout. N’envia un en carregar-se i un altre cada cop que canvia l’alçada del contingut, el tema o la direcció del text:

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

Camp	Tipus	Descripció
`contentHeight`	`number`	L’alçada natural del contingut de la pàgina en píxels CSS, incloent-hi la barra superior
`colorScheme`	`'light' \| 'dark'`	El tema amb què es mostra la pàgina. Amb colors de marca blanca, ho decideix el teu color de fons, no la configuració del dispositiu
`dir`	`'ltr' \| 'rtl'`	La direcció del text de l’idioma de la pàgina

Per rebre didit:layout al teu iframe, afegeix sdk_presentation=embedded a la URL de verificació. A partir de la versió 0.5.0, el SDK de JavaScript defineix la presentació per tu. Sense el paràmetre de presentació, la pàgina utilitza el seu disseny independent i no envia missatges de disseny.

Aquest host segueix les mides recomanades: una targeta fixa a partir de 1024px d’amplada, pantalla completa fins a 540px i, entremig, un iframe de 500px d’amplada que ocupa l’alçada que indica la pàgina:

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

Entre 541px i 1023px, aquest exemple utilitza una alçada inicial de 700px fins que arriba un missatge de disposició, limitada al 90% de l’alçada visible de la finestra. Les mides d’ordinador i de telèfon s’apliquen de seguida. En telèfons, l’iframe cobreix tota la finestra, així que ofereix una manera de sortir de la verificació al teu host. Fes servir colorScheme i dir per ajustar els controls que dibuixis al voltant de l’iframe al tema i a la direcció del text de la pàgina. Si la connexió de l’usuari es perd, la pàgina mostra una pantalla «Sense connexió a Internet» que es tanca sola quan torna la connexió. Si l’usuari tria Surt de la verificació en aquella pantalla, la pàgina envia didit:error amb error: "network_error" i després didit:cancelled: tanca l’iframe en rebre didit:cancelled.

Per a una experiència modal cuidada que se superposa a la teva pàgina:

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>

Component de React

Un component de React reutilitzable per a la verificació en modal:

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>
  );
}

Ús

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
          }
        }}
      />
    </>
  );
}

Component de 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>

Configuració

Permisos obligatoris

Fes servir aquesta llista completa de permisos per a la captura, la ubicació, la còpia i la compatibilitat de mitjans:

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

Permís	Per a què s’utilitza i què passa sense ell
`camera`	Escaneig de documents i captura del rostre. Sense aquest permís, la càmera no es pot iniciar i l’usuari veu una guia per habilitar l’accés a la càmera
`microphone`	Àudio opcional durant la captura de vídeo del document i del rostre. Sense aquest permís, la captura continua sense àudio
`geolocation`	El pas d’ubicació llegeix la posició del dispositiu. Sense aquest permís, l’usuari veu L’accés a la ubicació està desactivat, encara que hagi permès la ubicació al navegador
`clipboard-write`	Còpia de la referència de la sessió o de l’enllaç de verificació, inclosa la pantalla del navegador integrat a l’aplicació. Sense aquest permís, l’acció de còpia pot fallar i l’usuari ha de copiar manualment el text visible o l’adreça del navegador
`fullscreen`	Permet que els controls de mitjans sol·licitin la pantalla completa. Sense aquest permís, aquests controls es mantenen dins de l’iframe
`autoplay`	Permet que els vídeos instructius i les previsualitzacions de la càmera es reprodueixin automàticament, segons les normes del navegador. Sense aquest permís, la reproducció pot esperar una acció de l’usuari
`encrypted-media`	Es conserva per a la compatibilitat amb mitjans protegits. Els passos de captura actuals no el necessiten; sense aquest permís, la reproducció de mitjans protegits quedaria bloquejada
`digital-credentials-get`	Compartir un document d’identitat digital d’una cartera, com Google Wallet, mitjançant l’API de credencials digitals del navegador. Sense aquest permís, el navegador rebutja la sol·licitud de la cartera dins del vostre iframe, de manera que l’usuari no pot compartir-hi un document d’identitat des de la cartera

L’atribut allow delega els permisos; no substitueix l’elecció de l’usuari ni una capçalera Permissions-Policy més restrictiva de la vostra pàgina.

Mida de l’iframe

El flux de verificació s’adapta a la mida del seu iframe. Dimensiona l’iframe per a la finestra on es mostra:

Amplada de la finestra	Mida recomanada de l’iframe
1024px o més (ordinador)	960px per 660px, com a màxim el 90% de l’amplada i l’alçada de la finestra. Mantén aquesta mida en tots els passos
De 541px a 1023px	500px d’amplada i tant d’alçada com calgui pel contingut: pren l’alçada de `contentHeight` del missatge `didit:layout`, com a màxim el 90% de l’alçada de la finestra
540px o menys (telèfon)	Pantalla completa: tota l’amplada i tota l’alçada visible de la finestra, sense cantonades arrodonides

Per al rang intermedi, comença amb 500px per 700px fins que arribi el primer missatge didit:layout, amb el mateix límit d’alçada. L’exemple de didit:layout aplica les tres mides, incloses les de l’ordinador i del telèfon abans que arribi cap missatge.

Política de seguretat de contingut (CSP)

Si fas servir CSP, afegeix Didit a la directiva frame-src:

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

Verificació entre dispositius

L’iframe InContext admet automàticament la verificació entre dispositius:

L’usuari inicia la verificació a l’ordinador
Si la càmera no està disponible, es mostra un codi QR
L’usuari escaneja el codi QR amb el mòbil
L’usuari completa la verificació al mòbil
L’iframe de l’ordinador s’actualitza automàticament amb el resultat

Això passa automàticament: no cal cap configuració addicional.

Resolució de problemes

La càmera no funciona

Assegura’t que l’iframe inclou la llista completa de permisos
Comprova que el lloc es publica mitjançant HTTPS
Verifica que l’usuari ha concedit els permisos de càmera al teu domini
Prova el mètode de redirecció si falla l’accés a la càmera des de l’iframe

L’iframe no es carrega

Comprova si hi ha problemes amb la Política de seguretat de contingut (CSP)
Afegeix https://verify.didit.me a la directiva frame-src
Revisa la consola del navegador per veure si hi ha errors

No es rep postMessage

Verifica que escoltes l’origen correcte (https://verify.didit.me, o el teu domini de marca blanca)
Comprova que el receptor d’esdeveniments s’afegeix abans d’obrir l’iframe
Comprova el nom i l’estructura de l’esdeveniment: els tipus tenen prefix (didit:completed, no verification_complete) i el payload és dins de event.data.data

Repositori d’exemples

Repositori a GitHub

Consulta el codi font i els exemples a GitHub

Guies

Autenticació

Model Context Protocol (MCP)

SDK web

SDK natius

SDK de servidor

Integracions

Verificació d'identitat amb iframe: KYC web integrat

Visió general

Iframe amb UniLink (sense backend)

Què necessites

Implementació

Beneficis principals

Iframe amb sessió d’API (amb backend)

Quan utilitzar-lo

Implementació

Escoltar esdeveniments (postMessage)

Ajusta la mida de l’iframe amb `didit:layout`

HTML/CSS/JS

Component de React

Ús

Component de Vue

Configuració

Permisos obligatoris

Mida de l’iframe

Política de seguretat de contingut (CSP)

Verificació entre dispositius

Resolució de problemes

La càmera no funciona

L’iframe no es carrega

No es rep postMessage

Repositori d’exemples

Repositori a GitHub

​Visió general

​Iframe amb UniLink (sense backend)

​Què necessites

​Implementació

​Beneficis principals

​Iframe amb sessió d’API (amb backend)

​Quan utilitzar-lo

​Implementació

​Escoltar esdeveniments (postMessage)

​Ajusta la mida de l’iframe amb didit:layout

​Implementació modal

​HTML/CSS/JS

​Component de React

​Ús

​Component de Vue

​Configuració

​Permisos obligatoris

​Mida de l’iframe

​Política de seguretat de contingut (CSP)

​Verificació entre dispositius

​Resolució de problemes

​La càmera no funciona

​L’iframe no es carrega

​No es rep postMessage

​Repositori d’exemples

Repositori a GitHub

Visió general

Iframe amb UniLink (sense backend)

Què necessites

Implementació

Beneficis principals

Iframe amb sessió d’API (amb backend)

Quan utilitzar-lo

Implementació

Escoltar esdeveniments (postMessage)

Ajusta la mida de l’iframe amb `didit:layout`

Implementació modal

HTML/CSS/JS

Component de React

Ús

Component de Vue

Configuració

Permisos obligatoris

Mida de l’iframe

Política de seguretat de contingut (CSP)

Verificació entre dispositius

Resolució de problemes

La càmera no funciona

L’iframe no es carrega

No es rep postMessage

Repositori d’exemples