Vérification d'identité par iframe : KYC web intégré

Intégrez le parcours de vérification Didit directement dans votre application à l’aide d’une iframe. Vos utilisateurs restent ainsi sur votre site, sans redirection.

Vue d’ensemble

Fonctionnalité	UniLink (sans backend)	Session API (avec backend)
Temps de configuration	< 1 minute	5 à 10 minutes
Backend requis	❌ Non	✅ Oui
`vendor_data` personnalisé	❌ Non	✅ Oui
`metadata` personnalisé	❌ Non	✅ Oui
URL de rappel par session	❌ Non	✅ Oui
Suivi des sessions	❌ Non	✅ Oui

Iframe UniLink (sans backend requis)

La façon la plus rapide de commencer : copiez-collez simplement votre URL UniLink.

De quoi vous avez besoin

Un workflow Didit (créé dans la Console Didit)
Votre URL UniLink (cliquez sur Copy Link sur votre workflow)

Implémentation

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

⚠️ Obligatoire : l’attribut allow est indispensable pour accéder à la caméra pendant la détection du vivant.

Avantages principaux

Configuration en moins d’une minute : aucun backend, aucune clé API
Zéro configuration : URL de rappel définie dans les paramètres du workflow
Idéal pour les MVP : démarrez immédiatement

Iframe de session API (avec backend)

Pour les intégrations avancées qui nécessitent une personnalisation par session.

Quand l’utiliser

Transmettre des vendor_data ou metadata personnalisés par session
Définir des URL de rappel différentes par session
Suivre les sessions côté serveur avant le début de la vérification
Associer les sessions à vos identifiants utilisateur

Implémentation

Étape 1 : créer une session (backend) La réponse de création de session contient un champ nommé url : utilisez-le comme 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 });
});

Étape 2 : intégrer 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>

Écouter les événements (postMessage)

La page de vérification envoie des événements à la fenêtre parente. Chaque message respecte cette enveloppe :

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

Le payload est imbriqué : lisez event.data.data.sessionId, et 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
  }
});

Événements clés : 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, et didit:layout ({ contentHeight, colorScheme, dir }, voir ci-dessous). La référence des événements du SDK JavaScript répertorie les événements de vérification disponibles sous forme de callbacks typés. À partir de la version 0.5.0, le SDK gère en interne les messages de mise en page au lieu de les transmettre à onEvent.

Dimensionner l’iframe avec `didit:layout`

La page de vérification indique l’espace dont elle a besoin grâce à un message didit:layout. Elle en envoie un au chargement, puis un autre à chaque changement de hauteur de contenu, de thème ou de direction du texte :

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

Champ	Type	Description
`contentHeight`	`number`	La hauteur naturelle du contenu de la page en pixels CSS, barre supérieure incluse
`colorScheme`	`'light' \| 'dark'`	Le thème dans lequel la page s’affiche. Avec des couleurs en marque blanche, c’est la couleur de fond de votre site qui le détermine, et non le réglage de l’appareil
`dir`	`'ltr' \| 'rtl'`	La direction du texte de la langue de la page

Pour recevoir didit:layout dans votre propre iframe, ajoutez sdk_presentation=embedded à son URL de vérification. À partir de la version 0.5.0, le SDK JavaScript définit la présentation à votre place. Sans paramètre de présentation, la page utilise sa mise en page autonome et n’envoie aucun message de mise en page.

Cet hôte suit les tailles recommandées : une carte fixe à partir de 1024 px de large, un affichage en plein écran à 540 px et moins, et, entre les deux, une iframe de 500 px de large qui prend la hauteur indiquée par la page :

<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 541 px et 1023 px, cet exemple utilise une hauteur de départ de 700 px tant qu’aucun message de mise en page n’arrive, plafonnée à 90 % de la hauteur visible de la fenêtre. Les tailles pour ordinateur et téléphone s’appliquent immédiatement. Sur téléphone, l’iframe couvre la fenêtre : prévoyez donc un moyen de quitter la vérification dans votre application hôte. Utilisez colorScheme et dir pour adapter les contrôles placés autour de l’iframe au thème et à la direction du texte de la page. Si la connexion de l’utilisateur est interrompue, la page affiche un écran « Aucune connexion Internet » qui se ferme automatiquement dès que la connexion revient. Si l’utilisateur choisit Exit Verification sur cet écran, la page envoie didit:error avec error: "network_error", puis didit:cancelled : fermez l’iframe à la réception de didit:cancelled.

Implémentation en modale

Pour une expérience modale soignée qui se superpose à votre page :

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>

Composant React

Un composant React réutilisable pour la vérification en 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>
  );
}

Utilisation

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

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

Configuration

Autorisations requises

Utilisez cette liste complète d’autorisations pour la capture, la géolocalisation, la copie et la compatibilité des médias :

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

Autorisation	Utilisation et conséquence en l’absence de cette autorisation
`camera`	Numérisation du document et capture du visage. Sans elle, la caméra ne peut pas démarrer et l’utilisateur voit des instructions d’accès à la caméra
`microphone`	Audio facultatif pendant la capture vidéo du document et du visage. Sans elle, la capture se poursuit sans audio
`geolocation`	L’étape de localisation lit la position de l’appareil. Sans elle, l’utilisateur voit L’accès à la position est désactivé, même s’il a autorisé la localisation dans le navigateur
`clipboard-write`	Copie de la référence de session ou du lien de vérification, y compris sur l’écran du navigateur intégré à l’application. Sans elle, l’action de copie peut échouer et l’utilisateur doit copier manuellement le texte visible ou l’adresse du navigateur
`fullscreen`	Permet aux commandes multimédias de demander le plein écran. Sans elle, ces commandes restent à l’intérieur de l’iframe
`autoplay`	Permet la lecture automatique des vidéos explicatives et des aperçus de la caméra, sous réserve des règles du navigateur. Sans elle, la lecture peut attendre une action de l’utilisateur
`encrypted-media`	Conservée pour la compatibilité avec les médias protégés. Les étapes de capture actuelles n’en ont pas besoin ; sans elle, la lecture de médias protégés serait bloquée
`digital-credentials-get`	Partage d’une pièce d’identité numérique depuis un portefeuille comme Google Wallet, via l’API Digital Credentials du navigateur. Sans elle, le navigateur refuse la demande du portefeuille dans votre iframe, et l’utilisateur ne peut donc pas partager une pièce d’identité depuis le portefeuille à cet endroit

L’attribut allow délègue des autorisations ; il ne remplace ni le choix de l’utilisateur ni un en-tête Permissions-Policy plus strict sur votre page hôte.

Taille de l’iframe

Le parcours de vérification s’adapte à la taille de son iframe. Dimensionnez l’iframe selon la fenêtre dans laquelle elle est affichée :

Largeur de la fenêtre	Taille d’iframe recommandée
1024px et plus (ordinateur)	960px par 660px, au maximum 90 % de la largeur et de la hauteur de la fenêtre. Conservez cette taille à chaque étape
541px à 1023px	500px de large et d’une hauteur égale à celle du contenu : prenez la hauteur à partir de `contentHeight` du message `didit:layout`, au maximum 90 % de la hauteur de la fenêtre
540px et moins (téléphone)	Plein écran : toute la largeur et toute la hauteur visible de la fenêtre, sans coins arrondis

Pour la plage intermédiaire, commencez à 500px par 700px jusqu’à l’arrivée du premier message didit:layout, avec le même plafond de hauteur. L’exemple du message didit:layout applique les trois tailles, y compris celles pour ordinateur et téléphone, avant l’arrivée de tout message.

Content Security Policy (CSP)

Si vous utilisez CSP, ajoutez Didit à votre directive frame-src :

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

Vérification multi-appareils

L’iframe InContext prend automatiquement en charge la vérification multi-appareils :

L’utilisateur démarre la vérification sur ordinateur
Si la caméra est indisponible, un code QR s’affiche
L’utilisateur scanne le code QR avec son mobile
L’utilisateur termine la vérification sur son mobile
L’iframe sur ordinateur se met automatiquement à jour avec le résultat

Cela se produit automatiquement, sans configuration supplémentaire.

Dépannage

La caméra ne fonctionne pas

Vérifiez que l’iframe inclut la liste complète des autorisations
Vérifiez que votre site est servi en HTTPS
Vérifiez que l’utilisateur a accordé l’autorisation caméra à votre domaine
Essayez la méthode Redirect si l’accès à la caméra dans l’iframe échoue

L’iframe ne se charge pas

Vérifiez les problèmes liés à la Content Security Policy (CSP)
Ajoutez https://verify.didit.me à votre directive frame-src
Consultez la console du navigateur pour repérer les erreurs

postMessage non reçu

Vérifiez que vous écoutez la bonne origine (https://verify.didit.me, ou votre domaine en marque blanche)
Vérifiez que l’écouteur d’événements est ajouté avant l’ouverture de l’iframe
Vérifiez le nom et la forme de l’événement : les types sont préfixés (didit:completed, et non verification_complete) et le payload est imbriqué sous event.data.data

Exemple de dépôt

Dépôt GitHub

Consultez le code source et les exemples sur GitHub

Guides

Authentification

Model Context Protocol (MCP)

SDK web

SDK natifs

SDK serveur

Intégrations

Vérification d'identité par iframe : KYC web intégré

Vue d’ensemble

Iframe UniLink (sans backend requis)

De quoi vous avez besoin

Implémentation

Avantages principaux

Iframe de session API (avec backend)

Quand l’utiliser

Implémentation

Écouter les événements (postMessage)

Dimensionner l’iframe avec `didit:layout`

Implémentation en modale

HTML/CSS/JS

Composant React

Utilisation

Composant Vue

Configuration

Autorisations requises

Taille de l’iframe

Content Security Policy (CSP)

Vérification multi-appareils

Dépannage

La caméra ne fonctionne pas

L’iframe ne se charge pas

postMessage non reçu

Exemple de dépôt

Dépôt GitHub

​Vue d’ensemble

​Iframe UniLink (sans backend requis)

​De quoi vous avez besoin

​Implémentation

​Avantages principaux

​Iframe de session API (avec backend)

​Quand l’utiliser

​Implémentation

​Écouter les événements (postMessage)

​Dimensionner l’iframe avec didit:layout

​Implémentation en modale

​HTML/CSS/JS

​Composant React

​Utilisation

​Composant Vue

​Configuration

​Autorisations requises

​Taille de l’iframe

​Content Security Policy (CSP)

​Vérification multi-appareils

​Dépannage

​La caméra ne fonctionne pas

​L’iframe ne se charge pas

​postMessage non reçu

​Exemple de dépôt

Dépôt GitHub

Vue d’ensemble

Iframe UniLink (sans backend requis)

De quoi vous avez besoin

Implémentation

Avantages principaux

Iframe de session API (avec backend)

Quand l’utiliser

Implémentation

Écouter les événements (postMessage)

Dimensionner l’iframe avec `didit:layout`

Implémentation en modale

HTML/CSS/JS

Composant React

Utilisation

Composant Vue

Configuration

Autorisations requises

Taille de l’iframe

Content Security Policy (CSP)

Vérification multi-appareils

Dépannage

La caméra ne fonctionne pas

L’iframe ne se charge pas

postMessage non reçu

Exemple de dépôt