워터폴 플로우

k-ID를 사용한 연령 확인은 사용자가 개인정보를 공개하지 않고 연령을 증명할 수 있도록 하는 개인정보 보호 프로세스입니다. 이 접근 방식은 워터폴 플로우 모델을 사용합니다.

워터폴 플로우

AgeKit+는 연령 확인의 단일 지점 오케스트레이터로 작동하여 사용자의 연령을 확인하기 위해 확인 제공업체의 워터폴을 자동으로 연쇄합니다. 실제로 k-ID에 대한 하나의 API 호출이 구성된 방법을 순차적으로 제시합니다. 예를 들어 이메일 추론이나 얼굴 연령 추정으로 시작한 다음 필요에 따라 ID 문서 스캔이나 다른 방법으로 대체하여 사용자의 연령이 확인되거나 모든 옵션이 소진될 때까지 진행합니다. 이는 개발자가 k-ID의 API와 한 번 통합하고 플랫폼이 배후에서 여러 확인 기술을 시도하여 방법을 결합하여 확인 성공 가능성을 극대화함을 의미합니다.

확인 흐름은 iframe이나 모바일 웹 보기에 호스팅될 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을 사용하여 웹사이트나 앱에 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 요소를 제어하는 데 가장 좋지만, 데이터 무결성을 위해 실제 결과는 웹훅이나 /age-verification/get-status 호출에서 가져와야 합니다.

클라이언트 측(DOM 이벤트) - 응답 본문의 URL이 iframe에 포함된 경우 Verification.Result 구조로 부모 프레임에 창 메시지(MessageEvent)로 전송됩니다.

서버 측(웹훅) - Verification.Result 이벤트 형식으로 등록된 웹훅에 이벤트가 전송됩니다.

창 메시지 액세스 예시:

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result") {
    // 즉시 UI 업데이트를 위해 DOM 이벤트 사용
    updateUI(message);
  }
};

window.addEventListener("message", handleMessage);

important

데이터 무결성을 위해 항상 웹훅의 이벤트나 /age-verification/get-status 호출로 결과를 확인하세요. DOM 이벤트에만 의존하지 마세요. DOM 이벤트는 반응형 UI 업데이트에 가장 적합합니다.

창 이벤트와 웹훅 이벤트의 데이터 요소에는 다음 속성이 포함됩니다.

속성	설명
`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 웹훅을 통해 이벤트를 보내는 것 외에도 확인 상태를 쿼리할 수도 있습니다. 이는 등록된 웹훅이 일정 기간 동안 도달할 수 없었고 상태 이벤트가 전송되지 않은 경우를 처리하는 데 유용합니다. 확인 상태를 가져오려면 /age-verification/get-status API를 사용하세요. 반환되는 데이터 구조는 웹훅에 전송되는 Verification.Result 이벤트 데이터와 동일합니다. 웹훅 이벤트에 대한 자세한 내용은 웹훅을 참조하세요.

확인 시도 제한

각 확인 요청은 사용 가능한 확인 방법당 사용자에게 세 번의 시도를 허용합니다. 다음 경우 확인이 실패합니다:

사용 가능한 모든 확인 방법이 소진되고 연령을 결정할 수 없는 경우
연령이 결정되지만 기준에 필요한 임계값보다 낮은 경우

확인이 실패하면 사용자가 새로운 확인 시도를 시작하도록 허용할 수 있습니다. 그러나 확인 시스템의 오용 및 남용을 방지하기 위해 추가 확인 시도에 대한 속도 제한을 구현해야 합니다. 예를 들어 24시간 내에 사용자를 세 번의 확인 시도로 제한할 수 있습니다.

여러 확인 요청에 걸쳐 시도를 추적하려면 확인 요청의 subject.id 필드를 사용하세요. 이 필드에는 사용자에 대한 일관된 식별자(예: 임시 세션 ID 또는 해시된 사용자 ID)가 포함되어야 하며, 이를 통해 다음을 수행할 수 있습니다:

사용자당 확인 시도 횟수 추적
시간 기반 속도 제한 구현(예: 24시간당 3회 시도)
새 세션을 만들어 제한을 우회하는 사용자 방지

모범 사례

확인 요청을 시작하기 전에 서버에서 속도 제한을 구현하세요. 이를 통해 불필요한 API 호출을 방지하고 시스템을 남용으로부터 보호하는 데 도움이 됩니다.

확인 방법

사용 가능한 모든 확인 방법에 대한 자세한 내용은 확인 방법을 참조하세요.