연령 확인

새로운 규정이 플랫폼에 특정 기능이나 콘텐츠에 대한 액세스를 제공하기 전에 사용자 연령을 확인하도록 요구함에 따라 연령 확인이 점점 더 중요해지고 있습니다. k-ID의 Compliance Development Kit는 현지 법적 요구 사항에 맞춰 조정되는 포괄적이고 관할권을 인식하는 확인 시스템을 제공하여 규정 준수를 간단하게 만듭니다.

이 가이드는 몇 가지 단계로 연령 확인을 구현하는 과정을 안내하여 규제 요구 사항을 빠르게 충족하면서 원활한 사용자 경험을 제공할 수 있도록 합니다.

k-ID Dev Explorer 사용해보기

k-ID Dev Explorer라는 오픈 소스 개발자 샌드박스를 사용하여 연령 확인 흐름을 테스트하고 이벤트 로그에서 모든 트래픽을 볼 수 있습니다. 또한 이를 자신의 연령 확인 구현을 위한 시작점으로 사용할 수 있습니다.

사전 요구 사항

시작하기 전에 다음이 필요합니다:

1. k-ID 제품: k-ID Compliance Studio에서 제품 생성 및 구성
2. API 키: Compliance Studio의 제품 개발자 설정 페이지에서 API 키 생성
3. 웹훅 엔드포인트 (선택 사항이지만 권장): 확인 결과를 받을 보안 HTTPS 엔드포인트 설정. 자세한 내용은 웹훅을 참조하세요.

1단계: 연령 확인 시작

/age-verification/perform-access-age-verification API를 호출하여 확인 요청을 생성합니다. 이는 사용자가 연령 확인을 완료할 수 있는 고유한 URL을 반환합니다.

팁

API 키와 함께 API 참조를 사용하여 연령 확인 URL을 빠르게 생성하세요.

중요

구현의 경우 API 키가 클라이언트 측 코드에 노출되지 않도록 서버 간 호출이어야 합니다.

요청 예시

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

{
  "jurisdiction": "GB",
  "criteria": {
    "ageCategory": "ADULT"
  }
}

응답 예시

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

jurisdiction 매개변수는 현지 규정 준수를 보장하며(예: 영국 요구 사항의 경우 "GB" 설정), ageCategory: "ADULT" 기준은 사용자가 해당 관할권에서 정의된 연령 기준 요구 사항을 충족하는지 확인합니다.

2단계: 확인 인터페이스 표시

반환된 URL을 사용하여 웹사이트나 앱에 iframe을 만듭니다. 사용자는 이 인터페이스를 통해 확인을 완료하며, 사용 가능한 방법은 관할권 요구 사항에 맞게 자동으로 조정됩니다.

HTML 구현

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

iframe은 다음과 같은 여러 확인 방법을 사용자에게 제공합니다:

• AgeKey: 초기 확인 프로세스 후 생성되는 재사용 가능하고 익명의 연령 증명
• 얼굴 연령 추정: 기기의 카메라를 사용한 개인정보 보호 연령 추정
• ID 문서 확인: 정부 발급 ID 확인

사용 가능한 특정 방법은 관할권과 제품 구성에 따라 다릅니다. 자세한 내용은 확인 방법을 참조하세요.

3단계: 확인 결과 처리

사용자가 연령 확인을 성공적으로 완료했거나 최대 재시도 횟수에 도달했지만 성공하지 못한 경우 확인 결과를 받을 수 있습니다. 구현은 클라이언트 측 및 서버 측 방법의 조합을 사용해야 합니다: 클라이언트 측 이벤트는 UI 요소를 제어하는 데 가장 좋지만, 데이터 무결성을 위해 실제 결과는 웹훅이나 /age-verification/get-status 호출에서 가져와야 합니다.

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

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

const handleMessage = (event) => {
  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();
    }
  }
};

window.addEventListener("message", handleMessage);

서버 측 (웹훅, API 호출)

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

웹훅

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

웹훅 엔드포인트를 구성하여 Verification.Result 이벤트를 받습니다:

{
  "eventType": "Verification.Result",
  "data": {
    "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
    "status": "PASS",
    "ageCategory": "adult",
    "method": "id-document",
    "age": {
      "low": 25,
      "high": 25
    }
  }
}

API 호출

확인 ID로 /age-verification/get-status를 사용하여 확인 상태를 쿼리합니다:

GET /api/v1/age-verification/get-status?id=7854909b-9124-4bed-9282-24b44c4a3c97

Response:
{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "status": "PASS",
  "ageCategory": "adult",
  "method": "id-document"
}

다음 단계는 무엇인가요?

이제 기본 연령 확인을 구현했으므로 다음 리소스를 탐색하여 통합을 향상시키세요:

• API 참조 문서: 모든 연령 확인 API의 상세 문서
• 확인 방법: 제품에 대한 특정 확인 방법 및 시나리오 구성
• 웹훅 설정: 프로덕션 시스템을 위한 강력한 웹훅 처리 구현
• 모범 사례: 보안 및 안정적인 사용자 경험을 보장하기 위한 모범 사례 구현
• 런칭 전 체크리스트: 라이브 전 요구 사항 검토 (최신 체크리스트는 k-ID 지원팀에 문의)

k-ID의 연령 확인 API를 사용하면 사용자에게 원활하고 개인정보 보호 중심의 확인 경험을 제공하면서 연령 확인 규정을 빠르게 준수할 수 있습니다.