본문으로 건너뛰기

모범 사례

연령 게이트 모범 사례​

항상 연령 게이트 요구 사항 확인​

연령 정보를 수집하기 전에 항상 플레이어의 관할권으로 /age-gate/get-requirements를 호출하세요. 이를 통해 다음을 보장합니다:

  • 필요한 경우에만 연령 게이트 표시(shouldDisplay = true)
  • 관할권에 대해 승인된 연령 수집 방법만 사용
  • 연령 임계값 이해(디지털 동의 연령, 민사 연령, 최소 연령)
  • 연령 보증이 필요한지 여부 알기

모든 연령 게이트 확인 응답 처리​

/age-gate/check를 호출할 때 가능한 세 가지 상태를 모두 처리합니다:

  • PROHIBITED: 플레이어가 최소 연령 미만 - 액세스를 완전히 차단
  • CHALLENGE: 플레이어가 부모 동의 필요 - Challenge 생성 및 표시
  • PASS: 플레이어가 계속 진행 가능 - 세션 검색 또는 생성

응답 상태를 확인하지 않고 플레이어가 진행할 수 있다고 가정하지 마세요.

VPC 및 Challenge 모범 사례​

Challenge ID를 지속적으로 저장​

/age-gate/check에서 CHALLENGE 상태가 반환되면 Challenge ID를 로컬 스토리지나 서버에 저장하세요. 이를 통해 다음을 수행할 수 있습니다:

  • 동의가 부여되기 전에 플레이어가 돌아오면 동의 흐름 재개
  • 후속 방문에서 동일한 Challenge 정보(QR 코드, OTP) 표시
  • /challenge/get를 사용하여 Challenge 세부 정보 검색

Challenge 상태에 웹훅 사용(권장)​

폴링 대신 Challenge.StateChange 이벤트를 받도록 웹훅을 구성하세요. 웹훅은 다음을 제공합니다:

  • 동의가 부여되거나 거부될 때 실시간 업데이트
  • API 호출 감소 및 성능 향상
  • 더 안정적인 상태 추적

폴링을 사용해야 하는 경우 적절한 속도 제한을 구현하세요:

  • /challenge/get-status 호출 사이에 최소 5초
  • 항상 HTTP 429 응답을 확인하고 적절한 재시도 로직 구현
  • 적절한 타임아웃 제한 설정

신뢰할 수 있는 성인에게 효과적으로 알림​

Challenge가 생성되면 신뢰할 수 있는 성인이 동의를 완료할 수 있는 여러 방법을 제공하세요:

  • 이메일 알림: 이메일 주소가 사용 가능한 경우 /challenge/send-email 호출
  • QR 코드 표시: Challenge 응답에서 반환된 QR 코드 URL 표시
  • OTP 입력: 수동 입력을 위한 일회용 비밀번호 표시

고객 서비스 목적으로 Challenge 상태 응답에서 approverEmail을 저장하세요.

세션 관리 모범 사례​

세션을 적절히 캐시​

세션은 로컬 또는 클라우드 스토리지에 캐시되어야 하며 플레이어의 계정과 연결되어야 합니다. 세션은 다음 경우에만 변경됩니다:

  • 부모가 권한을 업데이트할 때
  • 플레이어가 다음 연령 카테고리로 "연령 상승"할 때
  • 부모나 플레이어가 세션을 삭제할 때

효율적인 세션 검색을 위해 ETag 사용​

/session/get API는 etag 매개변수를 사용하여 조건부 요청을 지원합니다. 캐시된 세션의 ETag를 포함하세요:

  • 세션이 변경되지 않은 경우 API는 HTTP 304(수정되지 않음)를 반환합니다
  • 이를 통해 불필요한 데이터 전송을 줄이고 성능을 향상시킵니다
  • 게임이 재시작될 때마다 항상 세션을 새로고침하세요

세션 웹훅 구현​

세션 관련 이벤트를 받도록 웹훅을 구성하세요:

이를 통해 폴링 없이 실시간 업데이트를 제공하고 게임이 권한 변경 사항을 즉시 반영하도록 보장합니다.

세션 업그레이드를 올바르게 처리​

플레이어가 부모 동의가 필요한 추가 권한을 요청할 때:

  • /session/upgrade를 사용하여 새 권한에 대한 Challenge 생성
  • 권한 업그레이드 위젯을 사용하여 동의 워크플로 처리
  • 웹훅이나 폴링을 통해 세션 변경 사항을 모니터링하여 업그레이드가 승인되었는지 감지

권한 모범 사례​

권한 상태 존중​

각 권한에 대해 enabled 및 managedBy 필드를 항상 확인하세요:

  • enabled: true: 플레이어에 대해 기능을 활성화할 수 있음
  • enabled: false: 기능을 꺼야 함
  • managedBy: PLAYER: 플레이어가 직접 활성화/비활성화할 수 있음
  • managedBy: GUARDIAN: 신뢰할 수 있는 성인만 활성화/비활성화할 수 있음
  • managedBy: PROHIBITED: 기능이 절대 허용되지 않음 - UI에서 완전히 제거

게임 기능에 권한을 올바르게 매핑​

각 k-ID 권한이 게임의 해당 기능에 올바르게 매핑되었는지 확인하세요. 권한은 다음에 대한 액세스를 제어해야 합니다:

  • 연령 제한 콘텐츠
  • 부모 동의가 필요한 기능
  • 데이터 수집 기능
  • 통신 기능

게임의 기능 세트와 일치하도록 Compliance Studio에서 권한을 구성하세요.

보안 권장 사항​

서버 전용 API 호출​

중요

모든 위젯 URL 생성 엔드포인트는 서버에서만 호출해야 하며 클라이언트 측 코드에서 직접 호출해서는 안 됩니다.

k-ID API 키는 보호해야 하는 비밀 자격 증명입니다:

  • 비밀 관리자를 사용하여 API 키를 안전하게 저장
  • 프론트엔드 JavaScript, 모바일 앱 코드 또는 클라이언트 측 코드에 API 키를 노출하지 마세요
  • 클라이언트 기기나 클라이언트 측 스토리지에 API 키를 저장하지 마세요

대상 원본 구성​

CDK는 Compliance Studio에서 대상 원본을 구성하는 기능을 제공하여 어떤 도메인이 위젯을 포함할 수 있는지 제어합니다. 이 설정은 Content Security Policy의 frame-ancestors 지시문을 제어합니다. 선택적 보안 조치로서 위험 허용 범위를 평가하고 보안 요구 사항을 기반으로 대상 원본 제한을 구현할지 결정하는 것이 좋습니다.

구성 옵션:

  • 특정 도메인: 프로덕션 사용을 위한 정확한 도메인 설정(예: https://yourgame.com)
  • 와일드카드 하위 도메인: 하위 도메인에 와일드카드 패턴 사용(예: https://*.yourgame.com)
  • 제한 없음: 제한 없는 포함을 위해 비워두거나 *로 설정(프로덕션에는 권장되지 않음)

보안 이점: 대상 원본은 공격자가 악의적인 사이트의 투명한 iframe에 규정 준수 흐름을 포함하여 다른 콘텐츠를 오버레이하고 사용자가 실수로 확인 요소를 클릭하도록 속이는 것을 방지합니다.

중요

구현 참고 사항:

  • 각 환경(테스트/라이브)에 대해 별도의 대상 원본 구성
  • 라이브 전에 모든 프로덕션 엔드포인트에 대해 대상 원본이 올바르게 구성되었는지 확인하세요.
  • 와일드카드를 사용하지 않는 경우 각 하위 도메인에는 자체 항목이 필요합니다
정보

대상 원본 설정과 관계없이 특정 k-ID 페이지만 iframe에 포함할 수 있습니다(확인 페이지, 위젯 및 VPC 흐름). 다른 모든 k-ID 페이지(가족 관리, 계정 설정)는 항상 iframe 포함에서 차단됩니다.

iframe 권한​

iframe allow 속성에 필요한 권한을 항상 포함하세요:

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

권한 분석:

  • camera - 얼굴 연령 추정에 필요(사용하는 경우)
  • payment - 신용카드 확인에 필요(사용하는 경우)
  • publickey-credentials-create - AgeKey 생성에 필요(사용하는 경우)
  • publickey-credentials-get - AgeKey 확인에 필요(사용하는 경우)

원본 검증​

들어오는 메시지의 원본을 항상 검증하세요:

window.addEventListener('message', (event) => {
  // 환경에 따라 원본 검증
  const validOrigins = [
    'https://family.k-id.com',        // 라이브 환경
    'https://family.test.k-id.com'    // 테스트 환경
  ];
  
  if (!validOrigins.includes(event.origin)) {
    return; // 승인되지 않은 원본의 메시지 무시
  }
  
  // 이벤트 처리
  handleWidgetEvent(event.data);
});

계정 시스템 통합​

제품 컨텍스트 매핑​

여러 게임에 걸친 계정 시스템과 CDK를 통합할 때:

  • Compliance Studio에서 각 게임을 자체 k-ID 제품에 매핑
  • 전역 권한을 위해 계정 시스템 자체에 대한 별도의 k-ID 제품 생성
  • 각 제품 컨텍스트에 대해 올바른 API 키 사용
  • 제품 간 세션 검색을 위해 계정 시스템에 세션의 kuid 저장

여러 제품에 대한 세션 캐싱​

계정 시스템에서 제품 ID별로 세션을 캐시하세요:

  • k-ID 제품 ID를 캐시 키로 사용
  • 새 VPC 흐름을 트리거하기 전에 기존 세션 확인
  • 제품에 대한 세션이 이미 있는 경우 추가 동의 없이 플레이어가 계속할 수 있도록 허용

관할권 처리​

API 호출을 할 때 항상 올바른 관할권을 전달하세요:

  • 플레이어의 위치나 IP 주소에서 관할권 결정
  • 관할권별 연령 임계값 및 요구 사항 사용
  • 게임플레이 중 관할권 변경을 /session/update-jurisdiction 호출로 처리