임베디드 흐름

CDK는 단일 인터페이스 내에서 완전한 Verifiable Parental Consent (VPC) 흐름을 처리하는 End-to-End 위젯을 제공하며, 연령 게이트, VPC, 데이터 고지, 권한 및 기본 설정을 모두 하나의 원활한 경험으로 다룹니다.

End-to-End 위젯이란 무엇인가요?

End-to-End 위젯은 단일 인터페이스에서 완전한 규정 준수 흐름을 처리하는 포괄적인 솔루션으로, 연령 게이트, VPC, 데이터 고지, 권한 및 기본 설정을 모두 하나의 원활한 경험으로 다룹니다. 이 위젯은 부모가 자녀의 기기나 자신의 기기에서 사용할 수 있어 동의 프로세스에 최대한의 유연성을 제공합니다.

위젯 URL 생성

/widget/generate-e2e-url API를 호출하여 완전한 VPC 흐름을 처리하는 end-to-end 위젯 URL을 만듭니다. 이것은 사용자가 연령 수집 및 부모 동의 프로세스를 완료할 수 있는 고유 URL을 반환합니다.

요청 예시

POST /api/v1/widget/generate-e2e-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA"
}

구성 플래그

선택적 flags 매개변수를 사용하면 건너뛸 흐름 부분을 사용자 정의할 수 있습니다:

• skipDataNotices: 데이터 고지 및 동의 수집 건너뛰기
• skipVerification: 확인 단계 건너뛰기
• skipPermissions: 권한 관리 건너뛰기
• skipPreferences: 기본 설정 건너뛰기

플랫폼 연령 신호 전달(선택 사항)

게임이 이미 플랫폼(Apple iOS, Google Play, Xbox, Meta Horizon 또는 이전 k-ID 확인)의 연령 데이터를 가지고 있다면, 요청 본문에 platformAgeSignal로 포함하세요. 위젯은 이 신호를 내부 연령 게이트 검사로 전달하므로, 확인된 신호가 성인을 나타낼 때 연령 게이트를 건너뛰고, 추가 확인 단계 없이 확인된 연령 권한을 충족하며, 신호와 플레이어가 자체 신고한 연령 사이의 충돌을 감지할 수 있습니다.

POST /api/v1/widget/generate-e2e-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "platformAgeSignal": {
    "name": "apple-ios",
    "ageLow": 18,
    "ageHigh": 25,
    "declarationType": "governmentIDChecked"
  }
}

지원되는 플랫폼과 필드 형식은 플랫폼 연령 신호를 참조하세요.

응답 예시

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

위젯 URL 표시

위젯 URL은 호스팅된 웹 페이지입니다. 애플리케이션에 적합한 환경에서 열어주세요:

• 웹 앱: iframe에 포함(아래 예 참조), 팝업 창에서 열기, 또는 전체 페이지 리디렉션.
• 모바일 앱: 시스템 브라우저 구성요소(Android의 Custom Tabs, iOS의 ASWebAuthenticationSession)에서 위젯 URL을 열고, options.redirectUrl을 전달하여 앱으로 돌아오는 딥 링크로 결과를 받으세요. 표시 방법은 모바일 앱 빠른 시작을 참조하세요. 가장 브랜드에 통합된 경험을 원한다면 사용자 정의 워크플로로 연령 게이트와 동의 UX를 네이티브로 구축하는 것을 고려하세요.
• 콘솔 (Switch, PlayStation, Xbox): 콘솔 브라우저는 일반적으로 제한되어 있거나 존재하지 않습니다. 위젯 URL을 QR 코드로 표시하여 플레이어가 페어링된 모바일 기기에서 흐름을 완료하도록 합니다. 모바일 기기의 리디렉션은 콘솔로 돌아갈 수 없으므로, 결과는 webhook과 /session/get 폴링으로 받으세요.

위젯 내에서 사용 가능한 방법은 호스트와 관계없이 관할권 요구 사항에 자동으로 적응합니다.

웹 예시

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

모바일 환경의 경우, /widget/generate-e2e-url을 호출할 때 options.redirectUrl을 전달하고 앱에서 콜백을 처리하세요. 엔드 투 엔드 예시는 모바일 앱 빠른 시작 가이드를 참조하세요.

이벤트 처리

연령 게이트 흐름이 완료되면 플레이어의 권한과 연령 상태를 저장하기 위해 세션이 생성됩니다. 흐름에 챌린지가 필요할 때마다 챌린지가 생성됩니다. 이는 확인 가능한 보호자 동의 또는 플레이어가 보호자 동의를 건너뛸 수 있는 연령을 신고한 경우의 Automatic age assurance를 위한 것입니다.

위젯은 수신할 수 있는 JavaScript 이벤트를 발생시킵니다. Widget.AgeGate.Result 이벤트를 수신하세요. 이 이벤트의 data.status는 흐름이 어떻게 종료되었는지를 나타냅니다:

• PASS: 플레이어가 연령 게이트를 통과했으며 세션이 생성되었습니다. data.sessionId가 존재합니다.
• FAIL: 필요한 챌린지가 통과되지 않았습니다(예: 신뢰할 수 있는 성인이 보호자 동의를 거부했거나 플레이어가 Automatic age assurance를 완료하지 않은 경우). 세션이 생성되지 않습니다.
• PROHIBITED: 플레이어가 이 관할 구역에서 제품의 최소 연령에 미달하여 계속 진행할 수 없습니다. 세션이 생성되지 않으며, data.age에 입력된 연령이 포함됩니다. 플레이어의 계속 진행을 차단하세요.

흐름 중에 챌린지가 생성된 경우 이벤트에는 challengeId도 포함됩니다. 챌린지 관련 이벤트에 대한 자세한 내용은 Widget.AgeGate.Challenge를 참조하세요.

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }

  const message = event.data;

  if (message.eventType === 'Widget.AgeGate.Result') {
    if (message.data.status === 'PASS') {
      const sessionId = message.data.sessionId;

      // challengeId가 있으면 흐름 중에 챌린지가 해결된 것입니다
      // (예: 보호자 동의 또는 Automatic age assurance).
      if (message.data.challengeId) {
        console.log('Challenge resolved, session issued:', sessionId);
      } else {
        console.log('Session created (no challenge required):', sessionId);
      }

      grantAccess(sessionId);
    } else if (message.data.status === 'FAIL') {
      // 필요한 챌린지가 통과되지 않았습니다(예: 보호자 동의가 거부되었거나
      // Automatic age assurance가 완료되지 않음). 세션 없음.
      console.log('Age gate not passed');
      restrictAccess();
    } else if (message.data.status === 'PROHIBITED') {
      // 플레이어가 제품의 최소 연령에 미달합니다.
      // 세션이 생성되지 않습니다. 계속 진행을 차단합니다.
      console.log('Player below minimum age:', message.data.age);
      restrictAccess();
    }
  }

  // 필요한 경우 챌린지 관련 이벤트 처리
  if (message.eventType === 'Widget.AgeGate.Challenge') {
    if (message.data.status === 'FAIL') {
      // 보호자가 동의를 거부. 액세스를 제한
      console.log('Consent denied');
      restrictAccess();
    }
  }

  if (message.eventType === 'Widget.ExitReview') {
    // 사용자가 '완료'를 클릭할 때 위젯 UI를 닫습니다
    closeWidget();
  }
});

리디렉션 URL로 결과 받기

시스템 브라우저 서피스(ASWebAuthenticationSession, SFSafariViewController, Chrome Custom Tabs)와 전체 페이지 최상위 리디렉션은 DOM 리스너를 노출할 수 없으므로, 대신 redirectUrl 콜백으로 연령 게이트 결과를 받습니다. /widget/generate-e2e-url 또는 /widget/generate-age-gate-url를 호출할 때 options.redirectUrl을 전달하세요. 이 URL은 http(s)와 사용자 정의 스키마 모바일 딥링크(예: myapp://age-gate/return)를 지원합니다.

연령 게이트 흐름이 완료되면 k-ID는 Widget.AgeGate.Result 이벤트가 담고 있는 것과 동일한 결과 필드를 쿼리 매개변수로 추가하여 플레이어를 해당 URL로 이동시킵니다. 리디렉션 URL의 기존 쿼리 매개변수는 유지됩니다.

status 값은 DOM 이벤트와 일치합니다:

• PASS: 플레이어가 연령 게이트를 통과했으며 세션이 생성되었습니다. sessionId로 액세스를 허용합니다.
• FAIL: 필요한 챌린지가 통과되지 않았습니다(예: 보호자 동의가 거부되었거나 Automatic age assurance가 완료되지 않은 경우). 세션이 생성되지 않습니다.
• PROHIBITED: 플레이어가 이 관할 구역에서 제품의 최소 연령에 미달합니다. 세션이 생성되지 않습니다. 플레이어의 계속 진행을 차단하세요.

예를 들어, 최소 연령에 미달하는 플레이어는 다음 URL로 이동합니다:

myapp://age-gate/return?status=PROHIBITED&age=8

리디렉션 쿼리 매개변수는 신뢰할 수 있는 결과가 아니라 UX 힌트로 취급하세요. 액세스를 허용하기 전에 Challenge.StateChange webhook 또는 /session/get를 통해 서버 측에서 결과를 확인하세요.

위젯이 처리하는 항목

위젯은 자동으로 다음을 처리합니다:

• 연령 수집: 관할권에 적절한 연령 수집 방법
• 데이터 고지: Compliance Studio의 제품 구성에 따라 수락할 데이터 고지
• 권한: Compliance Studio의 제품 구성에 따라 관리할 권한
• 부모 동의 Challenge: 사용자가 미성년자로 판단되는 경우 신뢰할 수 있는 성인 승인을 위한 Challenge가 생성됩니다
• Automatic age assurance: 제품이 해당 관할권에 Automatic age assurance가 활성화된 경우, 신고된 연령이 부모 동의를 건너뛸 만큼 높은 플레이어는 세션이 발급되기 전에 위젯 내에서 신고한 연령을 증명하도록 요청받습니다(얼굴 연령 추정 또는 ID 문서).

특정 흐름은 관할권과 Compliance Studio의 제품 구성에 따라 다릅니다.

VPC 구현에 대한 자세한 내용은 빠른 시작 가이드를 참조하세요.