Verificação de identidade por iframe: KYC incorporado

Incorpore o fluxo de verificação da Didit diretamente na sua aplicação através de um iframe. Assim, obtém uma experiência contínua, sem redirecionar os utilizadores para fora do seu site.

Visão geral

Funcionalidade	UniLink (sem backend)	Sessão de API (com backend)
Tempo de configuração	< 1 minuto	5-10 minutos
Backend necessário	❌ Não	✅ Sim
`vendor_data` personalizado	❌ Não	✅ Sim
`metadata` personalizado	❌ Não	✅ Sim
Callback por sessão	❌ Não	✅ Sim
Acompanhamento de sessões	❌ Não	✅ Sim

Iframe UniLink (sem backend)

A forma mais rápida de começar: basta copiar e colar o seu URL do UniLink.

O que precisa

Um fluxo de verificação da Didit (criado na Didit Console)
O seu URL do UniLink (clique em Copy Link no seu fluxo)

Implementação

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

⚠️ Obrigatório: o atributo allow é obrigatório para o acesso à câmara durante a prova de vida.

Principais vantagens

Configuração em menos de 1 minuto: sem backend, sem chaves de API
Sem configuração: URL de retorno definido nas definições do fluxo
Ideal para MVPs: comece de imediato

Iframe da sessão de API (com backend)

Para integrações avançadas que precisam de personalização por sessão.

Quando usar

Transmitir vendor_data ou metadata personalizados por sessão
Definir URLs de retorno diferentes por sessão
Acompanhar sessões no servidor antes de a verificação começar
Associar sessões aos seus IDs de utilizador

Implementação

Passo 1: criar uma sessão (backend) A resposta de criação de sessão usa um campo chamado url. Use-o como src do 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 });
});

Passo 2: incorporar no 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>

Escutar eventos (postMessage)

A página de verificação envia eventos para a janela principal. Cada mensagem tem este envelope:

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

O payload está aninhado. Leia event.data.data.sessionId, e não 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
  }
});

Eventos principais: 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 }, ver abaixo). A referência de eventos do SDK JavaScript lista os eventos de verificação disponíveis como callbacks tipados. A partir da versão 0.5.0, o SDK trata das mensagens de layout internamente, em vez de as reencaminhar para onEvent.

Dimensionar o iframe a partir de `didit:layout`

A página de verificação indica quanto espaço precisa através de uma mensagem didit:layout. Envia uma ao carregar e outra sempre que a altura do conteúdo, o tema ou a direção do texto mudam:

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

Campo	Tipo	Descrição
`contentHeight`	`number`	A altura natural do conteúdo da página em pixels CSS, incluindo a barra superior
`colorScheme`	`'light' \| 'dark'`	O tema em que a página é apresentada. Com cores de marca branca, é a cor de fundo que define o tema, e não a definição do dispositivo
`dir`	`'ltr' \| 'rtl'`	A direção do texto do idioma da página

Para receber didit:layout no seu próprio iframe, adicione sdk_presentation=embedded ao URL de verificação. A partir da versão 0.5.0, o SDK JavaScript define a apresentação por si. Sem um parâmetro de apresentação, a página usa o layout autónomo e não envia mensagens de layout.

Esta aplicação anfitriã segue os tamanhos recomendados: um cartão fixo a partir de 1024px de largura, ecrã inteiro até 540px e, entre estes valores, um iframe com 500px de largura que assume a altura comunicada pela 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 e 1023px, este exemplo usa uma altura inicial de 700px até que chegue uma mensagem de layout, limitada a 90% da altura da janela visível. Os tamanhos de computador e de telemóvel aplicam-se de imediato. Nos telemóveis, o iframe cobre a janela, por isso disponibilize uma forma de sair da verificação na sua aplicação. Use colorScheme e dir para alinhar quaisquer controlos que desenhe em torno do iframe com o tema e a direção do texto da página. Se a ligação do utilizador cair, a página mostra um ecrã «Sem ligação à Internet» que se fecha sozinho assim que a ligação for restabelecida. Se o utilizador escolher Sair da verificação nesse ecrã, a página envia didit:error com error: "network_error" e, em seguida, didit:cancelled. Feche o iframe ao receber didit:cancelled.

Para uma experiência de modal elegante que se sobrepõe à sua 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>

Componente React

Um componente React reutilizável para verificação em 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>
  );
}

Utilização

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>

Configuração

Permissões necessárias

Use esta lista completa de permissões para a captura, a localização, a cópia e a compatibilidade de conteúdo multimédia:

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

Permissão	Utilização e o que acontece sem ela
`camera`	Digitalização do documento e captura do rosto. Sem ela, a câmara não pode ser iniciada e o utilizador vê orientações para permitir o acesso à câmara
`microphone`	Áudio opcional durante a captura de vídeo do documento e do rosto. Sem ela, a captura continua sem áudio
`geolocation`	O passo de localização lê a posição do dispositivo. Sem ela, o utilizador vê O acesso à localização está desativado, mesmo que tenha permitido a localização no navegador
`clipboard-write`	Cópia da referência da sessão ou da ligação de verificação, incluindo no ecrã do navegador da aplicação. Sem ela, a ação de copiar pode falhar e o utilizador tem de copiar manualmente o texto visível ou o endereço do navegador
`fullscreen`	Permite que os controlos de multimédia peçam o ecrã inteiro. Sem ela, esses controlos mantêm-se dentro do iframe
`autoplay`	Permite que os vídeos instrucionais e as pré-visualizações da câmara sejam reproduzidos automaticamente, sujeitos às regras do navegador. Sem ela, a reprodução pode aguardar uma ação do utilizador
`encrypted-media`	Mantida para compatibilidade com conteúdo multimédia protegido. Os passos de captura atuais não a exigem; sem ela, a reprodução de conteúdo protegido seria bloqueada
`digital-credentials-get`	Partilha de uma identidade digital a partir de uma carteira, como a Google Wallet, através da API Digital Credentials do navegador. Sem ela, o navegador recusa o pedido da carteira dentro do seu iframe, pelo que o utilizador não consegue partilhar uma identidade a partir da carteira nesse ponto

O atributo allow delega permissões; não se sobrepõe à escolha do utilizador nem a um cabeçalho Permissions-Policy mais restritivo na sua página de acolhimento.

Tamanho do iframe

O fluxo de verificação adapta a disposição dos seus elementos ao tamanho do respetivo iframe. Dimensione o iframe para a janela em que é apresentado:

Largura da janela	Tamanho recomendado do iframe
1024px ou mais (computador)	960px por 660px, no máximo 90% da largura e da altura da janela. Mantenha este tamanho em todos os passos
541px a 1023px	500px de largura e tanta altura quanto o conteúdo: obtenha a altura a partir do `contentHeight` da mensagem `didit:layout`, no máximo 90% da altura da janela
540px ou menos (telemóvel)	Ecrã inteiro: a largura total e a altura visível total da janela, sem cantos arredondados

Para o intervalo intermédio, comece com 500px por 700px até chegar à primeira mensagem didit:layout, com o mesmo limite de altura. O exemplo de didit:layout aplica os três tamanhos, incluindo os tamanhos de computador e de telemóvel antes de chegar qualquer mensagem.

Política de segurança de conteúdo (CSP)

Se utilizar CSP, adicione a Didit à diretiva frame-src:

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

Verificação entre dispositivos

O iframe InContext suporta automaticamente a verificação entre dispositivos:

O utilizador inicia a verificação no computador
Se a câmara não estiver disponível, é apresentado um código QR
O utilizador lê o código QR com o telemóvel
O utilizador conclui a verificação no telemóvel
O iframe do computador é atualizado automaticamente com o resultado

Isto acontece automaticamente, sem necessidade de configuração adicional.

Resolução de problemas

A câmara não funciona

Certifique-se de que o iframe inclui a lista completa de permissões
Verifique se o seu site é servido através de HTTPS
Confirme se o utilizador concedeu as permissões de câmara ao seu domínio
Experimente o método Redirect se o acesso à câmara no iframe falhar

O iframe não carrega

Verifique se existem problemas de Política de segurança de conteúdo (CSP)
Adicione https://verify.didit.me à diretiva frame-src
Verifique a consola do navegador para detetar erros

Mensagem postMessage não recebida

Confirme que está a escutar a origem correta (https://verify.didit.me, ou o seu domínio de marca branca)
Verifique se o ouvinte de eventos é adicionado antes de abrir o iframe
Verifique o nome e a estrutura do evento: os tipos têm prefixo (didit:completed, e não verification_complete) e o payload está aninhado em event.data.data

Repositório de exemplos

Repositório no GitHub

Consulte o código-fonte e os exemplos no GitHub

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

Verificação de identidade por iframe: KYC incorporado

Visão geral

Iframe UniLink (sem backend)

O que precisa

Implementação

Principais vantagens

Iframe da sessão de API (com backend)

Quando usar

Implementação

Escutar eventos (postMessage)

Dimensionar o iframe a partir de `didit:layout`

HTML/CSS/JS

Componente React

Utilização

Componente Vue

Configuração

Permissões necessárias

Tamanho do iframe

Política de segurança de conteúdo (CSP)

Verificação entre dispositivos

Resolução de problemas

A câmara não funciona

O iframe não carrega

Mensagem postMessage não recebida

Repositório de exemplos

Repositório no GitHub

​Visão geral

​Iframe UniLink (sem backend)

​O que precisa

​Implementação

​Principais vantagens

​Iframe da sessão de API (com backend)

​Quando usar

​Implementação

​Escutar eventos (postMessage)

​Dimensionar o iframe a partir de didit:layout

​Implementação do modal

​HTML/CSS/JS

​Componente React

​Utilização

​Componente Vue

​Configuração

​Permissões necessárias

​Tamanho do iframe

​Política de segurança de conteúdo (CSP)

​Verificação entre dispositivos

​Resolução de problemas

​A câmara não funciona

​O iframe não carrega

​Mensagem postMessage não recebida

​Repositório de exemplos

Repositório no GitHub

Visão geral

Iframe UniLink (sem backend)

O que precisa

Implementação

Principais vantagens

Iframe da sessão de API (com backend)

Quando usar

Implementação

Escutar eventos (postMessage)

Dimensionar o iframe a partir de `didit:layout`

Implementação do modal

HTML/CSS/JS

Componente React

Utilização

Componente Vue

Configuração

Permissões necessárias

Tamanho do iframe

Política de segurança de conteúdo (CSP)

Verificação entre dispositivos

Resolução de problemas

A câmara não funciona

O iframe não carrega

Mensagem postMessage não recebida

Repositório de exemplos