본문으로 건너뛰기

단일 방법 플로우

제품의 정적 구성을 사용하는 대신 API 호출을 통해 확인 방법을 동적으로 선택해야 하는 경우 방법별 엔드포인트를 사용하여 확인 방법을 선택하는 사용자 정의 UI를 만들 수 있습니다. 이 접근 방식을 통해 어떤 확인 방법이 제시되고 사용자가 이를 선택하는 방식을 완전히 제어할 수 있습니다.

팁

확인 방법이 제품 구성에 의해 결정되는 권장 접근 방식의 경우 워터폴 플로우를 참조하세요.

방법별 엔드포인트​

방법별 엔드포인트는 자동 방법 선택을 우회하고 선택된 방법에 대한 확인 프로세스로 직접 이동합니다. k-ID는 여러 방법별 엔드포인트를 제공합니다:

엔드포인트확인 방법
/age-verification/perform-facial-age-estimation얼굴 연령 추정 스캔
/age-verification/perform-id-verificationID 스캔 확인
/age-verification/perform-age-key-verificationAgeKey
/age-verification/perform-connect-id-verificationConnectID(호주)
/age-verification/perform-inference이메일 주소 연령 추정

확인 방법에 대한 자세한 내용(사용 가능한 방법 및 작동 방식 포함)은 확인 방법 가이드를 참조하세요. 사용 가능한 모든 연령 확인 엔드포인트의 전체 목록은 API 참조의 연령 확인 엔드포인트를 참조하세요.

사용자 정의 확인 UI 만들기​

방법별 엔드포인트를 사용하면 다음을 수행하는 사용자 정의 UI를 구축할 수 있습니다:

  1. 사용자에게 사용 가능한 확인 방법 표시
  2. 사용자가 선호하는 방법 선택
  3. 선택에 따라 적절한 엔드포인트 호출
  4. 선택한 방법이 실패하면 다른 방법으로 대체

요청 형식​

모든 연령 확인 엔드포인트는 동일한 요청 형식을 사용합니다:

속성설명필수?
jurisdiction연령 확인이 수행되어야 하는 관할권예
criteria연령 확인을 위한 기준예
subject.email사용자가 이메일 주소로 다른 컨텍스트에서 k-ID로 연령을 확인한 경우 사용자에게 다시 확인하도록 요청하는 대신 원래 연령이 반환됩니다아니오
subject.claimedAge사용자가 연령 게이트에서 연령을 요청받은 경우 연령 추정 프로세스에 알리는 데 사용됩니다아니오
subject.id여러 확인 방법에 걸쳐 여러 실패 시도를 보고하는 데 사용되는 식별자입니다아니오

요청 예시​

POST /api/v1/age-verification/perform-facial-age-estimation
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "criteria": {
    "ageCategory": "ADULT"
  },
  "subject": {
    "claimedAge": 23
  }
}

응답 형식​

모든 연령 확인 엔드포인트는 동일한 응답 형식을 반환합니다:

속성설명
id고유 확인 ID
urliframe에 사용자에게 제시되어야 하는 연령 확인 URL

응답 예시​

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

확인 위젯 포함​

확인 URL을 받으면 표준 접근 방식과 정확히 동일하게 iframe에 포함합니다:

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

확인 결과 받기​

구현은 클라이언트 측 및 서버 측 방법의 조합을 사용해야 합니다: 클라이언트 측 이벤트는 UI 요소를 제어하는 데 가장 좋지만, 데이터 무결성을 위해 실제 결과는 웹훅이나 /age-verification/get-status 호출에서 가져와야 합니다.

클라이언트 측(DOM 이벤트)​

확인이 완료되면 DOM 이벤트를 사용하여 반응형 UI 업데이트를 수행합니다. 이벤트 구조에 대한 자세한 내용은 Verification.Result를 참조하세요.

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  if (message.eventType === 'Verification.Result') {
    if (message.data.status === 'PASS') {
      // 사용자가 확인 통과 - 즉시 UI 업데이트
      console.log('Age verified:', message.data.ageCategory);
      updateUI();
    } else if (message.data.status === 'FAIL') {
      // 사용자가 확인 실패 - 즉시 UI 업데이트
      console.log('Verification failed:', message.data.failureReason);
      updateUI();
    }
  }
});

서버 측(웹훅, API 호출)​

데이터 무결성과 안정적인 상태 관리를 위해 웹훅이나 API 호출을 사용합니다. 데이터 무결성을 위해 항상 웹훅의 이벤트나 /age-verification/get-status 호출로 결과를 확인하세요. DOM 이벤트에만 의존하지 마세요.

웹훅​

웹훅 이벤트 구조에 대한 자세한 내용은 Verification.Result를 참조하세요.

Verification.Result 이벤트를 받을 웹훅 엔드포인트를 구성합니다. 자세한 내용은 웹훅을 참조하세요.

API 호출​

확인 ID로 /age-verification/get-status를 사용하여 확인 상태를 쿼리할 수 있습니다. 이는 결과가 전송되었을 때 웹훅이 도달할 수 없었던 경우에 유용합니다.

연령 항소​

확인이 실패하면 /age-verification/perform-age-appeal 엔드포인트를 호출하여 사용자가 항소하도록 허용할 수 있습니다. 이것은 사용자에게 ID 확인 및 신뢰할 수 있는 성인 증명 옵션을 제시합니다(연령 추정은 항소에 사용할 수 없음).

사용 가능한 엔드포인트​

다음은 일반적인 방법별 연령 확인 엔드포인트입니다:

엔드포인트설명
/age-verification/perform-facial-age-estimation얼굴 연령 추정만 제공
/age-verification/perform-id-verificationID 문서 확인만 제공
/age-verification/perform-age-key-verificationAgeKey 확인만 제공
/age-verification/perform-connect-id-verificationConnectID 확인만 제공
/age-verification/perform-inference이메일 연령 추정만 제공
/age-verification/perform-age-appeal이전에 실패한 확인용(ID 확인 및 신뢰할 수 있는 성인 증명만)
/age-verification/get-status확인 상태 쿼리

사용 가능한 모든 연령 확인 엔드포인트의 전체 및 최신 목록은 API 참조의 연령 확인 엔드포인트를 참조하세요.