瀑布流

{
  "jurisdiction": "US-CA",
  "criteria": {
    "ageCategory": "ADULT"
  },
  "options": {
    "facialAgeEstimation": {
      "passIfOver": 25,
      "failIfUnder": 12
    },
    "locale": "en-US",
    "redirectUrl": "https://example.com/verification-complete"
  }
}

https://example.com/verification-complete?verificationId=7854909b-9124-4bed-9282-24b44c4a3c97&result=PASS

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/verify?token=eyJ...",
  "shortUrl": "https://family.k-id.com/v/7854909b-9124-4bed-9282-24b44c4a3c97?pid=42&s=qr"
}

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

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result") {
    // 使用 DOM 事件进行即时 UI 更新
    updateUI(message);
  }
};

window.addEventListener("message", handleMessage);

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

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

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174002",
    "status": "FAIL",
    "failureReason": "max-attempts-exceeded"
  }
}

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "status": "FAIL",
    "method": "age-estimation-scan",
    "failureReason": "age-criteria-not-met",
    "age": {
      "low": 16,
      "high": 17
    }
  }
}

// ❌ 错误：假设 FAIL 时 method 和 age 始终存在
const handleVerification = (result: VerificationResult) => {
  if (result.data.status === "FAIL") {
    // 当 failureReason 为 max-attempts-exceeded 时，这些字段为 undefined
    logFailedMethod(result.data.method);
    recordFailedAge(result.data.age.low);
    showRetryWithMethod(result.data.method);
  }
};

// ✅ 正确：适当处理不同的失败场景
const handleVerification = (result: VerificationResult) => {
  if (result.data.status === "FAIL") {
    denyAccess();
    
    switch (result.data.failureReason) {
      case "max-attempts-exceeded":
        // 没有做出年龄判定 - 提供替代选项
        showMaxAttemptsMessage();
        offerSupportContact();
        // 考虑对未来尝试实施速率限制
        break;
        
      case "age-criteria-not-met":
        // 年龄已确定但不满足标准
        // method 和 age 字段可用
        if (result.data.age) {
          logDeterminedAge(result.data.age.low);
        }
        showAgeCriteriaNotMetMessage();
        break;
        
      case "fraudulent-activity-detected":
        // 处理可疑活动（参见下一节）
        handleSuspiciousActivity(result.data.id);
        break;
        
      default:
        // 优雅地处理未知失败原因
        logUnknownFailure(result.data.failureReason);
        showGenericFailureMessage();
    }
  }
};

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174003",
    "status": "FAIL",
    "failureReason": "fraudulent-activity-detected"
  }
}

// ❌ 错误：将欺诈活动视为正常失败
const handleVerification = (result: VerificationResult) => {
  if (result.data.status === "FAIL") {
    // 允许立即重试可能导致持续滥用
    showRetryButton();
    
    // 记录不存在的年龄数据
    analytics.track("verification_failed", {
      age: result.data.age?.low  // 欺诈活动时为 undefined
    });
  }
};

// ✅ 正确：实施适当的安全措施
const handleVerification = (result: VerificationResult) => {
  if (result.data.status === "FAIL") {
    denyAccess();
    
    if (result.data.failureReason === "fraudulent-activity-detected") {
      // 记录安全事件以供审查
      securityLog.warn("Fraudulent activity detected", {
        verificationId: result.data.id,
        timestamp: new Date().toISOString(),
        subjectId: currentSubjectId
      });
      
      // 实施更严格的速率限制或临时阻止
      applySecurityCooldown(currentSubjectId);
      
      // 显示适当的消息，不透露检测详情
      showVerificationUnavailableMessage();
      
      // 不提供立即重试 - 这可能导致持续滥用
      hideRetryOptions();
      
      // 可选择标记为手动审查
      flagForManualReview(result.data.id);
    }
  }
};

interface VerificationData {
  id: string;
  status: "PASS" | "FAIL";
  method?: string;
  ageCategory?: "adult" | "digital-youth" | "digital-minor"; // PASS 状态时始终存在
  age?: { low: number; high: number }; // PASS 状态时始终存在
  dob?: string;
  failureReason?: string;
}

const handleVerificationResult = (data: VerificationData) => {
  // 始终记录验证尝试
  logVerificationAttempt(data.id, data.status);
  
  if (data.status === "PASS") {
    // 授予访问权限 - 用户满足年龄标准
    grantAccess();
    
    // age 和 ageCategory 在 PASS 状态时始终存在
    storeAgeData(data.age.low, data.age.high);
    applyPermissionsForCategory(data.ageCategory);
    
    // 仅在存在时处理可选字段
    
    if (data.dob) {
      storeDateOfBirth(data.dob);
    }
    
    if (data.method) {
      analytics.track("verification_passed", { method: data.method });
    }
    
    return;
  }
  
  // 处理 FAIL 状态
  denyAccess();
  
  // failureReason 在 FAIL 状态下始终存在
  switch (data.failureReason) {
    case "age-criteria-not-met":
      // 此失败原因下 method 和 age 可用
      handleAgeCriteriaFailure(data);
      break;
      
    case "max-attempts-exceeded":
      // 没有年龄判定 - method 和 age 不可用
      handleMaxAttemptsFailure(data.id);
      break;
      
    case "fraudulent-activity-detected":
      // 安全事件 - method 和 age 不可用
      handleFraudulentActivity(data.id);
      break;
      
    default:
      // 始终优雅地处理未知失败原因
      handleUnknownFailure(data);
  }
};