\`Embed Didit identity verification into my web page using an iframe. \## Two Options \### Option A: UniLink (no backend — fastest setup) Copy your UniLink URL from Didit Console > Workflows > Copy Link. It looks like: https://verify.didit.me/u/ Embed it directly: \ ```> ⚠️ **必填**：活体检测期间访问摄像头必须设置 `allow` 属性。### 主要优势- **不到 1 分钟即可完成设置**，无需后端，无需 API 密钥 - **零配置**，回调 URL 在工作流设置中配置 - **适合 MVP**，可立即开始***## API 会话 iframe（需要后端）适用于需要按会话进行自定义的高级集成。### 适用场景- 为每次会话传入自定义 `vendor_data` 或 `metadata` - 为每次会话设置不同的回调 URL - 在验证开始前在服务端跟踪会话 - 将会话与您的用户 ID 关联### 实现**步骤 1：创建会话（后端）**会话创建响应使用名为 **`url`** 的字段，请将其用作 iframe 的 `src`。```javascript theme={null} // 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 }); }); ```**步骤 2：在 iframe 中嵌入（前端）**```html theme={null} ```***## 监听事件（postMessage）验证页面会向父窗口发送事件。每条消息都具有以下结构：```typescript theme={null} { type: 'didit:', // e.g. 'didit:completed' data: { /* payload */ }, // event-specific; may be undefined timestamp: 1718000000000 // ms epoch } ```payload 是**嵌套**的，请读取 `event.data.data.sessionId`，而不是 `event.data.sessionId`：```javascript theme={null} 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 } }); ```主要事件：`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`，以及 `didit:layout`（`{ contentHeight, colorScheme, dir }`，参见[下文](#根据-diditlayout-设置-iframe-尺寸)）。[JavaScript SDK 事件参考](https://docs.didit.me/zh/integration/web-sdks/javascript-sdk.md#事件参考)列出了可作为类型化回调使用的验证事件。从 0.5.0 版本开始，SDK 会在内部处理布局消息，而不会将其转发给 `onEvent`。### 根据 `didit:layout` 设置 iframe 尺寸验证页面会通过 `didit:layout` 消息告知所需的空间。页面加载时会发送一条消息，之后每当其内容高度、主题或文本方向发生变化时，都会再次发送：```typescript theme={null} { type: 'didit:layout', data: { contentHeight: 612, // CSS px colorScheme: 'light', // 'light' | 'dark' dir: 'ltr' // 'ltr' | 'rtl' }, timestamp: 1718000000000 } ```| 字段 | 类型 | 说明 | | - | - | - | | `contentHeight` | `number` | 页面内容的自然高度（CSS 像素），包括顶部栏 | | `colorScheme` | `'light' \| 'dark'` | 页面显示的主题。使用白标颜色时，由您的背景色决定主题，而不是设备设置 | | `dir` | `'ltr' \| 'rtl'` | 页面语言的文本方向 |> [!NOTE] > > 要在您自己的 iframe 中接收 `didit:layout`，请在其验证 URL 中添加 `sdk_presentation=embedded`。从 0.5.0 版本开始，[JavaScript SDK](https://docs.didit.me/zh/integration/web-sdks/javascript-sdk.md) 会自动为您设置展示方式。如果没有展示参数，页面将使用独立布局，并且不会发送布局消息。本宿主遵循[推荐尺寸](#iframe-尺寸)：宽度 1024px 及以上使用固定卡片，540px 及以下全屏显示，两者之间使用宽 500px 的 iframe，其高度取自页面报告的值：```html theme={null} ```在 541px 至 1023px 之间，此示例在收到布局消息前使用 700px 的初始高度，并且最高不超过可见窗口高度的 90%。电脑和手机尺寸会立即生效。在手机上 iframe 会覆盖整个窗口，因此请在宿主页面中提供退出验证的方式。请使用 `colorScheme` 和 `dir`，使您在 iframe 周围绘制的控件与页面的主题和文本方向保持一致。如果用户的网络连接中断，页面会显示“无网络连接”屏幕，网络恢复后该屏幕会自动关闭。如果用户在此屏幕上选择**退出验证**，页面会先发送 `didit:error`（`error: "network_error"`），然后发送 `didit:cancelled`：收到 `didit:cancelled` 时请关闭 iframe。***## 模态框实现如需在页面上叠加显示一个精致的模态框体验：### HTML/CSS/JS```html theme={null} ```***## React 组件用于模态框验证的可复用 React 组件：```tsx theme={null} 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(''); 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:', 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 (

e.target === e.currentTarget && onClose()} >