iframe本人確認：Webサイト埋め込み型KYC

iframeを使って、Diditの認証フローをアプリケーション内に直接埋め込めます。ユーザーをサイトの外へリダイレクトすることなく、シームレスな体験を提供できます。

概要

機能	UniLink (バックエンド不要)	API Session (バックエンドあり)
セットアップ時間	< 1分	5-10分
バックエンドが必要	❌ いいえ	✅ はい
カスタム`vendor_data`	❌ いいえ	✅ はい
カスタム`metadata`	❌ いいえ	✅ はい
セッションごとのコールバック	❌ いいえ	✅ はい
セッショントラッキング	❌ いいえ	✅ はい

UniLink iframe (バックエンド不要)

最も手軽に始められる方法です。UniLink URLをコピーして貼り付けるだけです。

必要なもの

Didit のワークフロー (Didit Consoleで作成)
UniLink URL (ワークフローのCopy Linkをクリック)

実装

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

⚠️ 必須: ライブネス検知中にカメラへアクセスするため、allow属性は必須です。

主なメリット

1分未満でセットアップ: バックエンドもAPIキーも不要
設定不要: コールバックURLはワークフローの設定で指定
MVPに最適: すぐに始められます

API Session iframe (バックエンドあり)

セッションごとのカスタマイズが必要な高度な連携向けです。

使用する場面

セッションごとにカスタムのvendor_dataやmetadataを渡す
セッションごとに異なるコールバックURLを設定する
認証開始前にサーバー側でセッションを追跡する
セッションを自社のユーザーIDと関連付ける

実装

ステップ1: セッションを作成する (バックエンド) セッション作成のレスポンスにはurlというフィールドが含まれます。これをiframeのsrcとして使用してください。

// 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に埋め込む (フロントエンド)

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

イベントの受信 (postMessage)

検証ページは親ウィンドウにイベントを送信します。すべてのメッセージは次の形式です。

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

ペイロードはネストされています。event.data.sessionIdではなく、event.data.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
  }
});

主なイベント: 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 }、後述を参照)。型付きコールバックとして利用できる認証イベントは、JavaScript SDKイベントリファレンスに記載されています。バージョン0.5.0以降、SDKはレイアウトメッセージをonEventに転送せず、内部で処理します。

`didit:layout`でiframeのサイズを調整する

検証ページは、必要な領域の大きさをdidit:layoutメッセージで通知します。このメッセージは読み込み時に1回送信され、その後もコンテンツの高さ、テーマ、テキストの方向が変わるたびに送信されます。

{
  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'`	ページの言語のテキスト方向

独自のiframeでdidit:layoutを受信するには、その認証URLにsdk_presentation=embeddedを追加してください。バージョン0.5.0以降は、JavaScript SDKがpresentationを自動で設定します。presentationパラメーターがない場合、ページはスタンドアロンのレイアウトを使用し、レイアウトメッセージを送信しません。

このホストページは推奨サイズに従っています。幅1024px以上では固定サイズのカード、540px以下では全画面、その中間では幅500pxでページが通知する高さを使うiframeになります。

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

541pxから1023pxの間では、この例はレイアウトメッセージを受け取るまで700pxの初期高さを使用し、表示中のウィンドウの高さの90%を上限とします。PC向けとスマートフォン向けのサイズ設定はすぐに適用されます。スマートフォンではiframeがウィンドウ全体を覆うため、ホスト側で認証を終了する手段を用意してください。iframeの周囲に配置するコントロールは、colorSchemeとdirを使ってページのテーマとテキスト方向に合わせてください。ユーザーの接続が切れると、ページには「No internet connection」画面が表示され、接続が回復すると自動的に閉じます。ユーザーがこの画面でExit Verificationを選択すると、ページはerror: "network_error"を含むdidit:errorを送信し、続いてdidit:cancelledを送信します。didit:cancelledを受け取ったらiframeを閉じてください。

モーダルの実装

ページに重ねて表示する洗練されたモーダルを実装するには:

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>

Reactコンポーネント

モーダル形式の認証に使える再利用可能なReactコンポーネント:

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

使い方

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

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>

設定

必要な権限

撮影、位置情報、コピー、メディアの互換性に対応するため、次の権限リストをすべて指定してください。

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

権限	用途と、権限がない場合の動作
`camera`	書類のスキャンと顔の撮影に使用します。この権限がないとカメラを起動できず、ユーザーにはカメラへのアクセスに関する案内が表示されます
`microphone`	書類と顔の動画撮影時に、任意で音声を録音するために使用します。この権限がない場合、撮影は音声なしで続行されます
`geolocation`	位置情報ステップでデバイスの位置を取得するために使用します。この権限がないと、ユーザーがブラウザで位置情報を許可していても、位置情報へのアクセスがオフですと表示されます
`clipboard-write`	セッション参照や認証リンクのコピーに使用します。アプリ内ブラウザの画面でも使用されます。この権限がないとコピーのアクションが失敗することがあり、ユーザーは表示されているテキストやブラウザのアドレスを手動でコピーする必要があります
`fullscreen`	メディアコントロールが全画面表示をリクエストできるようにします。この権限がない場合、これらのコントロールはiframe内にとどまります
`autoplay`	ブラウザのルールの範囲内で、説明動画やカメラのプレビューを自動再生できるようにします。この権限がない場合、再生がユーザーのアクションを待つことがあります
`encrypted-media`	保護されたメディアとの互換性のために残しています。現在の撮影ステップでは不要ですが、この権限がない場合、保護されたメディアの再生はブロックされます
`digital-credentials-get`	ブラウザのDigital Credentials APIを通じて、Google Walletなどのウォレットからデジタル身分証明書を共有するために使用します。この権限がないと、ブラウザはiframe内でのウォレットへのリクエストを拒否するため、ユーザーはそこでウォレットから身分証明書を共有できません

allow属性は権限を委譲するものです。ユーザーの選択や、ホストページに設定されたより厳しいPermissions-Policyヘッダーを上書きすることはありません。

iframeのサイズ

認証フローは、iframeのサイズに合わせてレイアウトを調整します。iframeは、表示するウィンドウに合わせたサイズにしてください。

ウィンドウの幅	推奨されるiframeのサイズ
1024px以上（コンピューター）	960px×660px。ウィンドウの幅と高さの90%を上限とします。すべてのステップでこのサイズを維持してください
541px～1023px	幅500px、高さはコンテンツに合わせます。高さは`didit:layout`メッセージの`contentHeight`から取得し、ウィンドウの高さの90%を上限とします
540px以下（スマートフォン）	全画面表示。ウィンドウの幅全体と表示領域の高さ全体を使い、角丸はつけません

中間の範囲では、最初のdidit:layoutメッセージを受信するまで500px×700pxで表示し、高さの上限は同じにしてください。didit:layoutの例では、メッセージ受信前のコンピューターとスマートフォンのサイズも含め、3つのサイズすべてを適用しています。

コンテンツセキュリティポリシー (CSP)

CSPを使用している場合は、frame-srcディレクティブにDiditを追加してください。

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

クロスデバイス認証

InContext iframeは、クロスデバイス認証に自動で対応しています。

ユーザーがデスクトップで認証を開始します
カメラを使用できない場合、QRコードが表示されます
ユーザーがモバイル端末でQRコードをスキャンします
ユーザーがモバイル端末で認証を完了します
デスクトップのiframeが結果を受けて自動的に更新されます

これは自動的に行われるため、追加の設定は不要です。

トラブルシューティング

カメラが動作しない

iframeに権限リストがすべて含まれていることを確認します
サイトがHTTPSで配信されていることを確認します
ユーザーがお使いのドメインにカメラの権限を許可していることを確認します
iframeでのカメラへのアクセスが失敗する場合は、リダイレクト方式をお試しください

iframeが読み込まれない

コンテンツセキュリティポリシー（CSP）に問題がないか確認します
frame-srcディレクティブにhttps://verify.didit.meを追加します
ブラウザのコンソールにエラーが出ていないか確認します

postMessageを受信できない

正しいオリジン（https://verify.didit.me、またはホワイトラベルのドメイン）からのメッセージをリッスンしていることを確認します
iframeを開く前にイベントリスナーが追加されていることを確認します
イベント名と形式を確認します。タイプにはプレフィックスが付いており（verification_completeではなくdidit:completed）、ペイロードはevent.data.dataの下にネストされています

サンプルリポジトリ

GitHubリポジトリ

GitHubでソースコードとサンプルを確認できます

ガイド

認証

Model Context Protocol (MCP)

Web SDK

ネイティブSDK

サーバーSDK

連携

iframe本人確認：Webサイト埋め込み型KYC

概要

UniLink iframe (バックエンド不要)

必要なもの

実装

主なメリット

API Session iframe (バックエンドあり)

使用する場面

実装

イベントの受信 (postMessage)

`didit:layout`でiframeのサイズを調整する

モーダルの実装

HTML/CSS/JS

Reactコンポーネント

使い方

Vueコンポーネント

設定

必要な権限

iframeのサイズ

コンテンツセキュリティポリシー (CSP)

クロスデバイス認証

トラブルシューティング

カメラが動作しない

iframeが読み込まれない

postMessageを受信できない

サンプルリポジトリ

GitHubリポジトリ

​概要

​UniLink iframe (バックエンド不要)

​必要なもの

​実装

​主なメリット

​API Session iframe (バックエンドあり)

​使用する場面

​実装

​イベントの受信 (postMessage)

​didit:layoutでiframeのサイズを調整する

​モーダルの実装

​HTML/CSS/JS

​Reactコンポーネント

​使い方

​Vueコンポーネント

​設定

​必要な権限

​iframeのサイズ

​コンテンツセキュリティポリシー (CSP)

​クロスデバイス認証

​トラブルシューティング

​カメラが動作しない

​iframeが読み込まれない

​postMessageを受信できない

​サンプルリポジトリ

GitHubリポジトリ

概要

UniLink iframe (バックエンド不要)

必要なもの

実装

主なメリット

API Session iframe (バックエンドあり)

使用する場面

実装

イベントの受信 (postMessage)

`didit:layout`でiframeのサイズを調整する

モーダルの実装

HTML/CSS/JS

Reactコンポーネント

使い方

Vueコンポーネント

設定

必要な権限

iframeのサイズ

コンテンツセキュリティポリシー (CSP)

クロスデバイス認証

トラブルシューティング

カメラが動作しない

iframeが読み込まれない

postMessageを受信できない

サンプルリポジトリ