ウォーターフォールフロー

k-IDによる年齢確認は、ユーザーが個人情報を開示することなく年齢を証明できるプライバシー保護型のプロセスです。このアプローチはウォーターフォールフローモデルを使用します。

ウォーターフォールフロー

AgeKit+は年齢チェックの単一ポイントオーケストレーターとして機能し、ユーザーの年齢を確認するために確認プロバイダーのウォーターフォールを自動的にカスケードします。実際には、k-IDへの1つのAPI呼び出しで、設定された方法が順番に提示されます。たとえば、メール推論または顔年齢推定から始まり、必要に応じてID文書スキャンまたはその他の方法にフォールバックし、ユーザーの年齢が確認されるか、すべてのオプションが使い果たされるまで続きます。これは、開発者がk-IDのAPIと一度統合し、プラットフォームが背後で複数の確認技術を試行し、方法を組み合わせて確認の成功の可能性を最大化することを意味します。

確認フローは、iframeまたはモバイルWebビューでホストされるURLを返すAPI呼び出しで開始されます。ユーザーはこのインターフェースで確認プロセスを完了します。利用可能な確認方法は、Compliance Studioでの製品設定によって決定され、管轄区域の要件へのコンプライアンスが確保されます。

API	シナリオ
`/age-verification/perform-access-age-verification`	機能、成熟したコンテンツ、または製品自体へのアクセスを取得する前にユーザーの年齢を確認する場合。
`/age-verification/perform-trusted-adult-verification`	信頼できる大人（親または保護者）の確認を実行する場合。
`/age-verification/perform-age-appeal`	年齢確認に失敗したが、決定に異議を唱えたいユーザー向け。

年齢確認APIは、リクエストとレスポンスの形式に関して標準化されています。

リクエスト本文

プロパティ	説明	必須?
`jurisdiction`	年齢確認が行われる管轄区域	はい
`criteria`	年齢確認の基準	はい
`subject.email`	ユーザーがメールアドレスで他のコンテキストでk-IDで年齢を確認した場合、ユーザーに再度年齢を推定または証明するよう求める代わりに、元の年齢が返されます。	いいえ
`subject.claimedAge`	ユーザーが年齢ゲートで年齢を尋ねられた場合、年齢推定プロセスに通知するために使用されます	いいえ
`subject.id`	複数の確認方法にわたって複数の失敗した試行を報告するために使用される識別子。これは一時セッションID、またはハッシュ化されたユーザーIDです。	いいえ
`options.facialAgeEstimation.minAge`	顔年齢推定結果からの最小許容年齢。これは通常、年齢推定テクノロジーの固有の分散を考慮して、`criteria.age`より高く設定する必要があります。たとえば、要件が18歳以上の場合、`minAge`を21-25に設定すると、信頼性バッファが提供され、偽陽性が減少します。これにより、顔年齢推定に合格したユーザーが実際の年齢要件を満たす可能性が高くなります。	いいえ

サンプル：

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

レスポンス本文

年齢確認APIへの成功したリクエストは、以下のレスポンスを返します。

プロパティ	説明
`id`	年齢確認サービスによって生成された一意の確認ID
`url`	iframeに埋め込み、ユーザーに提示して自分自身を確認してもらう必要がある年齢確認URL。

サンプル：

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

確認インターフェースの埋め込み

返されたURLを使用して、Webサイトまたはアプリにiframeを作成します。ユーザーはこのインターフェースを通じて確認を完了し、利用可能な方法が管轄区域の要件に自動的に適応します。

<div id="verification-container">
  <iframe 
    id="verification-widget"
    src="VERIFICATION_URL" 
    width="100%" 
    height="600"
    frameborder="0"
    allow="camera;payment;publickey-credentials-get;publickey-credentials-create">
  </iframe>
</div>

allow属性は、以下の機能を有効にするために必要です：

camera: 顔年齢推定に必要
payment: クレジットカード確認に必要
publickey-credentials-getおよびpublickey-credentials-create: WebAuthnベースの確認方法に必要

確認結果

ユーザーが年齢確認を正常に完了したか、ユーザーが最大試行回数に達して成功しなかった場合、年齢確認結果はクライアント側とサーバー側の両方のチャネルを通じて配信されます。実装では、両方を組み合わせて使用する必要があります：クライアント側のイベントはUI要素を制御するのに最適ですが、データの整合性については、実際の結果はwebhookまたは/age-verification/get-statusへの呼び出しから取得する必要があります。

クライアント側（DOMイベント） - レスポンス本文のURLがiframeに含まれている場合、Verification.Result構造を持つウィンドウメッセージ（MessageEvent）として親フレームに送信されます。

サーバー側（webhooks） - イベントは、Verification.Resultイベントの形式で登録されたwebhookに送信されます。

ウィンドウメッセージにアクセスする例：

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result") {
    // DOMイベントを即座のUI更新に使用
    updateUI(message);
  }
};

window.addEventListener("message", handleMessage);

important

データの整合性については、DOMイベントのみに依存するのではなく、webhooksからのイベントまたは/age-verification/get-statusへの呼び出しで結果を常に確認してください。DOMイベントは応答性の高いUI更新に最適です。

ウィンドウイベントとwebhookイベントのデータ要素には、以下のプロパティが含まれます。

プロパティ	説明
`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,
        }
    }
}

ウィンドウイベントの処理：

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

確認エラー

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

イベント構造の詳細については、Verification.Errorを参照してください。

サンプルメッセージ：

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

確認ステータスの確認

JavaScriptとk-ID webhookの両方でイベントを送信することに加えて、確認のステータスをクエリすることも可能です。これは、登録されたwebhookが一定期間到達不能で、ステータスイベントが送信されなかった場合を処理するのに役立ちます。確認のステータスを取得するには、/age-verification/get-status APIを使用します。返されるデータ構造は、webhookに送信されるVerification.Resultイベントデータと同一です。webhookイベントの詳細については、Webhooksを参照してください。

確認試行の制限

各確認リクエストでは、利用可能な確認方法ごとにユーザーに3回の試行が許可されます。確認は、以下の場合に失敗します：

利用可能なすべての確認方法が使い果たされ、年齢を決定できない
年齢が決定されたが、基準の必要な閾値を下回る

確認が失敗した場合、ユーザーに新しい確認試行を開始することを許可できます。ただし、確認システムの誤用や悪用を防ぐために、追加の確認試行にレート制限を実装する必要があります。たとえば、24時間以内に3回の確認試行にユーザーを制限する場合があります。

確認リクエストのsubject.idフィールドを使用して、複数の確認リクエストにわたる試行を追跡します。このフィールドには、ユーザーの一貫した識別子（一時セッションIDまたはハッシュ化されたユーザーIDなど）を含める必要があり、以下を可能にします：

ユーザーごとの確認試行回数を追跡する
時間ベースのレート制限を実装する（たとえば、24時間あたり3回の試行）
ユーザーが新しいセッションを作成して制限を回避することを防ぐ

ベストプラクティス

確認リクエストを開始する前に、サーバーでレート制限を実装してください。これにより、不要なAPI呼び出しを防ぎ、システムを悪用から保護するのに役立ちます。

確認方法

利用可能なすべての確認方法の詳細については、確認方法を参照してください。