年齢確認 (Age Verification)

k-ID は、以下のシナリオでユーザーの年齢を確認するための API セットを提供します。

API	シナリオ
/age-verification/perform-access-age-verification	機能、成人向けコンテンツ、または製品自体へのアクセス前にユーザーの年齢を確認
/age-verification/perform-trusted-adult-verification	検証可能な保護者同意(VPC)のための信頼できる成人(親/保護者)確認
/age-verification/perform-facial-age-estimation	顔年齢推定のみで年齢確認を実施
/age-verification/perform-id-verification	政府発行の身分証明書による年齢確認のみを実施
/age-verification/perform-age-appeal	未成年の疑いがあるユーザーの製品アクセス復元前に年齢を確認

Age Verification API はリクエスト/レスポンス形式が標準化されています。

リクエストボディ (Request Body)

プロパティ	説明	必須
jurisdiction	年齢確認を行う法域	はい
criteria	年齢確認の判定基準	はい
subject.email	他のコンテキストで k-ID にメールアドレスで年齢確認済みの場合、再度の推定/証明を要求せず既存の年齢を返す	いいえ
subject.claimedAge	年齢ゲートでユーザーが申告した年齢(年齢推定の参考として使用)	いいえ
subject.id	失敗試行の集計に使用する識別子(一時セッション ID やハッシュ化ユーザー ID など)	いいえ

例:

{
  "jurisdiction": "US-CA",
  "subject": {
    "email": "user@example.com",
    "claimedAge": 23,
    "id": "3854909b-8888-4bed-9282-24b74c4a3c97"
  },
  "criteria": {
    "ageCategory": "DIGITAL_YOUTH_OR_ADULT"
  }
}

レスポンスボディ (Response Body)

成功したリクエストは次の構造を返します。

プロパティ	説明
id	Age Verification サービスが生成した一意の検証 ID
url	ユーザーが自己確認を行うために表示すべき年齢確認 URL

例:

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/verify?token=eyJhbGciOi..."
}

Verification Result

ユーザーが年齢確認を正常に完了した場合、または最大再試行回数に達しても成功しなかった場合、結果は 2 つの方法で配信されます。

1. 登録済みの Webhook に Verification.Result イベントを送信
2. 上記の URL を iFrame に含めた場合、親フレームに window メッセージ(MessageEvent)として送信

window メッセージの取得例:

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result") {
    // 結果処理ロジック
    console.log("eventData", message);
  }
};

window.addEventListener("message", handleMessage);

window イベントと Webhook の data 要素には次のプロパティが含まれます。

プロパティ	説明
id	この結果が属する検証 ID
status	ユーザーが年齢基準を満たしたかに応じて PASS または FAIL
ageCategory	リクエストで指定した法域におけるユーザーの年齢カテゴリ。adult、digital-youth、digital-minor をサポート
method	使用された確認方法。id-document、age-estimation、age-attestation、credit-card、social-security-number をサポート
failureReason	失敗理由。age-criteria-not-met、max-attempts-exceeded、fraudulent-activity-detected をサポート(status が FAIL の場合のみ設定)
age	推定または確認された年齢の下限/上限を low/high として返す

例:

{
  "eventType": "Verification.Result",
  "data": {
    "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
    "status": "PASS",
    "ageCategory": "adult",
    "method": "id-document",
    "age": {
      "low": 25,
      "high": 25
    }
  }
}

window イベント処理例:

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result" && ) {
    if (message.data.status === "PASS") {
      window.location.href = `https://www.example.com/success?verificationId=${message.data.id}`
    }
    if (message.data.status === "FAIL") {
      window.location.href = `https://www.example.com/fail?verificationId=${message.data.id}`
    }
  }
};

window.addEventListener("message", handleMessage);

Verification Error

予期しないエラーが発生した場合、実装側で適切に処理できるよう Javascript イベントが発火します。

メッセージ例:

{
  "eventType": "Verification.Error",
  "method": "credit-card",
  "status": "ERROR"
}

検証ステータスの確認 (Checking Verification Status)

Javascript のイベント送信および k-ID Webhook に加え、検証のステータスを照会することも可能です。これは、登録済みの Webhook が一時的に到達不能でステータスイベントを受信できなかったケースのハンドリングに有用です。ステータス照会には /age-verification/get-status API を使用します。返却データ構造は Webhook に送られる data 要素 と同一です。

サポートされる確認方法 (Supported Verification Methods)

製品・機能・コンテンツへのアクセス用であれば、k-ID はユーザーの年齢を確認するための複数手段を提供します。

方法	説明
age-estimation	プライバシー保護型の顔年齢推定。生体情報はユーザーのデバイス外に送信されない
id-verification	パスポートや運転免許証など政府発行の身分証明書を用いた年齢確認
age-attestation	検証済みの保護者が子どもの年齢を証明

k-ID は信頼できる成人確認専用の年齢証明手段も提供します。加えて、age-estimation など一部の手段は、法域によっては信頼成人確認用途で許可されない場合があります。

方法	説明
credit-card	成人が有効なクレジットカードを提示して契約年齢であることを証明
social-security-number	社会保障番号と一部個人情報の組み合わせで年齢を証明

Age Verification 連携テスト

k-ID API をコーディングする前に、API キーと API ドキュメント を使って、顔年齢推定を実際に試すことができます。

まずはシンプルな k-ID API 呼び出しの手順に従ってください。

同一ブラウザで /age-verification/perform-facial-age-estimation を呼び出します。リストから当該 API をクリックします。

続いて「Try it out」ボタンを押し、「Execute」ボタンを押します。

アプリ(または別ウィンドウ)で用いる iFrame の URL はレスポンスの url に含まれます。ブラウザに貼り付けてアクセスしてください。例:

https://family.k-id.com/verify?token=...

その後、案内ページが表示されます:

「Start」ボタンを押して顔年齢推定を試してください。セキュリティのためのライヴネスチェックに注意してください。本デモでは結果は画面に直接表示されず、Javascript イベントと Webhook の呼び出しで送信されます。カメラ情報がデバイス外に送信されることはありません。