연령 게이트

연령 게이트는 연령 제한 콘텐츠, 기능 또는 서비스에 대한 액세스를 허용하기 전에 사용자의 연령을 수집하고 확인하는 데 사용되는 메커니즘입니다. k-ID API는 연령 게이트를 관리하고 플레이어의 연령과 관할권을 기반으로 필요한 작업을 결정하는 엔드포인트를 제공합니다.

커스텀 연령 게이트 UI를 구축하고 계신가요?

연령 슬라이더, 날짜 선택기, 동의 흐름 및 접근성에 대한 디자인 권장 사항은 UX 가이드라인을 참조하세요.

연령 게이트 요구 사항 가져오기

플레이어의 관할권으로 /age-gate/get-requirements를 호출하여 다음을 결정합니다:

연령 게이트를 표시해야 하는지 여부(shouldDisplay)
승인된 연령 수집 방법(approvedAgeCollectionMethods)
연령 임계값:
- digitalConsentAge: 플레이어가 디지털 동의를 제공할 수 있는 최소 연령
- civilAge: 플레이어가 법적 성인으로 간주되는 민사/계약 연령
- minimumAge: 플랫폼/게임에 액세스하는 데 필요한 최소 연령
연령 보증이 필요한지 여부(ageAssuranceRequired)

요청 예시

GET /api/v1/age-gate/get-requirements?jurisdiction=US-CA
Authorization: Bearer your-api-key

응답 예시

{
  "shouldDisplay": true,
  "ageAssuranceRequired": true,
  "digitalConsentAge": 13,
  "civilAge": 18,
  "minimumAge": 0,
  "approvedAgeCollectionMethods": [
    "date-of-birth",
    "age-slider",
    "platform-account"
  ]
}

플랫폼 연령 신호 포함

게임에 플랫폼이 보고한 연령 신호(Apple iOS, Google Play, Xbox, Meta Horizon 또는 k-ID)가 있는 경우 쿼리 매개변수로 포함하세요: platformName, platformAgeLow, platformAgeHigh, platformCategory, platformDeclarationType, platformVerificationId. k-ID는 입력을 수집하기 전에 이 신호를 shouldDisplay와 ageAssuranceRequired에 반영합니다 — 확인된 성인 신호는 연령 게이트를 건너뛰고 확인된 연령 권한을 즉시 충족할 수 있게 합니다. 지원되는 플랫폼과 필드 형식의 전체 목록은 플랫폼 연령 신호를 참조하세요.

GET /api/v1/age-gate/get-requirements?jurisdiction=US-CA&platformName=apple-ios&platformAgeLow=18&platformAgeHigh=25&platformDeclarationType=governmentIDChecked
Authorization: Bearer your-api-key

액세스를 위한 연령 확인

플레이어의 연령을 수집한 후 생년월일과 관할권으로 /age-gate/check를 호출하여 다음 단계를 결정합니다:

PROHIBITED: 플레이어의 연령이 게임의 최소 연령 미만입니다. 플레이어는 계속 진행하는 것이 차단되어야 합니다.
CHALLENGE: 세션이 생성되기 전에 플레이어가 챌린지를 완료해야 합니다. challenge.type을 확인하여 어떤 챌린지가 반환되었는지 결정하세요:
- CHALLENGE_PARENTAL_CONSENT: 신고된 연령이 너무 어려서 플레이어가 부모 동의 없이 진행할 수 없습니다. 플레이어가 세션을 받기 전에 신뢰할 수 있는 성인이 승인해야 합니다.
- CHALLENGE_AGE_GATE_AGE_ASSURANCE: 신고된 연령은 플레이어가 부모 동의 없이 진행하기에 충분하지만, 제품에 Automatic age assurance가 활성화되어 있어 세션이 발급되기 전에 플레이어가 신고한 연령을 증명해야 합니다(일반적으로 얼굴 스캔 또는 ID 문서로).
PASS: 플레이어가 게임을 계속할 수 있으며 응답에 세션이 반환됩니다.

요청 예시

POST /api/v1/age-gate/check
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "dateOfBirth": "2015-04-15"
}

`CHALLENGE` 응답 예시

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
    "oneTimePassword": "ABC123",
    "type": "CHALLENGE_PARENTAL_CONSENT",
    "url": "https://family.k-id.com/authorize?otp=ABC123"
  }
}

`PASS` 응답 예시

{
  "status": "PASS",
  "session": {
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "ageStatus": "LEGAL_ADULT",
    "dateOfBirth": "2005-04-15",
    "jurisdiction": "US-CA",
    "permissions": [...],
    "status": "ACTIVE"
  }
}

플랫폼 연령 신호 포함

요청 본문에 platformAgeSignal 객체를 단독으로 또는 dateOfBirth/age/kuid와 함께 포함할 수 있습니다. 확인된 신호는 추가 확인 단계 없이 확인된 연령 권한을 충족하고 세션에 ageVerification을 기록하며, 확인되지 않은 신호도 연령 충돌 감지와 보수적인 연령 해석에 사용됩니다. 지원되는 플랫폼과 확인된 선언 유형은 플랫폼 연령 신호를 참조하세요.

POST /api/v1/age-gate/check
Content-Type: application/json
Authorization: Bearer your-api-key

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

Automatic age assurance

Automatic age assurance는 신고된 연령이 부모 동의를 건너뛸 만큼 높은 플레이어를 검증하는 선택적 제품 구성입니다. 활성화되면 k-ID는 원래 PASS 응답이 될 것을 가로채고 대신 CHALLENGE_AGE_GATE_AGE_ASSURANCE 챌린지를 반환합니다. 플레이어가 직접 얼굴 연령 추정 또는 ID 문서 검증을 완료하며(신뢰할 수 있는 성인은 관여하지 않음), 검증이 통과되면 k-ID가 세션을 생성합니다.

기능 활성화

Automatic age assurance를 활성화하는 것은 두 단계 프로세스입니다:

조직 수준 설정(allowAutomaticAgeAssurance)이 k-ID에 의해 부여되어야 합니다. 이 설정은 기본적으로 꺼져 있으며 k-ID만 전환할 수 있습니다. 조직에서 활성화하려면 k-ID 지원에 문의하세요.
설정이 켜지면 제품 관리자는 Compliance Studio의 제품 엔진 재정의에서 관할권별로 Automatic age assurance를 켜거나 끌 수 있습니다.

트리거 조건

다음의 모든 조건이 참인 경우 /age-gate/check가 CHALLENGE_AGE_GATE_AGE_ASSURANCE 챌린지를 반환합니다:

대상 관할권의 제품에 Automatic age assurance가 활성화되어 있습니다.
플레이어의 신고 연령이 부모 동의 없이 제품에 액세스할 수 있는 연령 이상입니다. 이는 일반적으로 관할권의 디지털 동의 연령이지만, 제품에 구성된 더 높은 minimum-age 또는 필수 권한 임계값에 의해 상향될 수 있습니다.
디지털 동의 연령 이상을 충족하는 신뢰할 수 있는 플랫폼 연령 신호가 요청과 함께 제공되지 않았습니다. 검증된 플랫폼 신호(예: declarationType: governmentIDChecked가 있는 apple-ios)는 이미 충분한 보증을 제공하므로 챌린지를 우회합니다.

원래 부모 동의가 필요한 신고에 대해서는 기존 CHALLENGE_PARENTAL_CONSENT 흐름이 대신 사용됩니다. Automatic age assurance는 부모 동의 경로를 변경하지 않습니다.

`CHALLENGE_AGE_GATE_AGE_ASSURANCE` 응답 예시

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "CHALLENGE_AGE_GATE_AGE_ASSURANCE",
    "url": "https://family.k-id.com/age-gate/verify?token=..."
  }
}

CHALLENGE_PARENTAL_CONSENT와 달리 응답에 oneTimePassword가 포함되지 않습니다. url은 신뢰할 수 있는 성인 동의 포털이 아닌 셀프 서비스 검증 페이지를 가리킵니다. 검증을 완료하는 사람은 플레이어 자신이므로 URL에 서명된 토큰이 포함되며 iframe으로 직접 임베드할 수 있습니다.

챌린지 처리

챌린지 유형을 감지하고 allow="camera;payment;publickey-credentials-get;publickey-credentials-create"가 있는 iframe에 challenge.url을 임베드합니다.
반응형 UI 업데이트를 위해 iframe에서 Verification.Result DOM 메시지를 수신합니다(Verification.Result 참조).
Challenge.StateChange Webhook 또는 /challenge/get-status 폴링을 통해 서버 측에서 결과를 확인합니다. PASS에서 data.sessionId에는 새로 생성된 세션이 포함됩니다.
sessionId로 /session/get을 호출하여 플레이어의 전체 권한을 가져옵니다.

코드 샘플이 포함된 안내는 사용자 정의 연령 게이트 빠른 시작 가이드의 자동 연령 보증 챌린지 처리를 참조하세요.

플랫폼 연령 카테고리 API 사용

일부 플랫폼은 특정 연령이나 생년월일이 아닌 연령 카테고리를 반환하는 API를 제공합니다. 예를 들어 Meta Horizon은 GetAgeCategory API를 제공하며 CH(아동, 10-12세), TN(청소년, 13-17세) 또는 AD(성인, 18세 이상)과 같은 카테고리를 반환합니다.

신호를 직접 전달

대부분의 통합에서는 변환 단계를 건너뛰고 platformAgeSignal을 /age-gate/check(그리고 /age-gate/get-requirements에는 쿼리 매개변수로) 직접 전송할 수 있습니다. k-ID는 카테고리에서 연령 범위로의 변환을 서버 측에서 처리하고, 확인된 신호의 선언 유형을 반영하며, 한 번의 호출로 연령 충돌 감지를 실행합니다. 플랫폼 연령 신호를 참조하세요. 자체 UI를 구동하기 위해 미리 연령 범위가 필요한 경우, 아래 변환 엔드포인트가 여전히 유용합니다.

플랫폼의 연령 카테고리 API를 사용할 때는 카테고리를 플레이어의 관할권에 대한 연령 범위로 변환한 다음 해당 연령 범위를 k-ID의 연령 게이트 시스템에서 사용해야 합니다.

예시: Meta Horizon의 GetAgeCategory API 사용

다음은 Meta Horizon의 연령 카테고리 API를 k-ID와 통합하는 방법에 대한 완전한 예시입니다:

Meta Horizon에서 연령 카테고리 가져오기

// Meta Horizon Unity SDK 예시
var ageCategory = PlatformService.GetAgeCategory();
// 반환: "CH"(아동, 10-12세), "TN"(청소년, 13-17세) 또는 "AD"(성인, 18세 이상)

카테고리를 연령 범위로 변환

POST /api/v1/age-gate/get-platform-age-range
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "platform": {
    "name": "meta-horizon",
    "category": "TN"
  }
}

응답:

{
  "ageLow": 13,
  "ageHigh": 17
}

연령 게이트 확인에서 최소 연령 사용

ageLow 값(이 예시에서는 13)을 /age-gate/check를 호출할 때 age 매개변수로 사용합니다:

POST /api/v1/age-gate/check
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "age": 13
}

이를 통해 플랫폼의 확인된 연령 카테고리가 관할권별 요구사항을 유지하면서 k-ID의 연령 게이트 시스템에서 사용할 수 있는 특정 연령 값으로 적절히 변환됩니다.

생년월일 형식

생년월일 형식 및 요구 사항에 대한 정보는 핵심 개념 섹션의 연령 게이트를 참조하세요.

기본 권한

/age-gate/get-requirements가 shouldDisplay = false로 응답하는 경우 연령 게이트를 표시하지 않아야 하며 플레이어의 생년월일이 정의되지 않습니다. 이 경우 게임은 여전히 /age-gate/get-default-permissions를 호출하여 관할권에 대한 기본 권한을 검색하여 Session을 생성합니다. 이는 이 관할권에서 권한이 연령에 따라 다르지 않음을 의미합니다. 게임의 일부 기능은 관할권에 따라 모든 연령대의 청중에게 금지될 수 있으므로 게임은 여전히 Session 권한을 참조하여 기능을 활성화할 수 있는지 확인해야 합니다.

연령 게이트 요구 사항 가져오기​

요청 예시​

응답 예시​

플랫폼 연령 신호 포함​

액세스를 위한 연령 확인​

요청 예시​

CHALLENGE 응답 예시​

PASS 응답 예시​

플랫폼 연령 신호 포함​

Automatic age assurance​

기능 활성화​

트리거 조건​

CHALLENGE_AGE_GATE_AGE_ASSURANCE 응답 예시​

챌린지 처리​

플랫폼 연령 카테고리 API 사용​

예시: Meta Horizon의 GetAgeCategory API 사용​

생년월일 형식​

기본 권한​

연령 게이트 요구 사항 가져오기

요청 예시

응답 예시

플랫폼 연령 신호 포함

액세스를 위한 연령 확인

요청 예시

`CHALLENGE` 응답 예시

`PASS` 응답 예시

플랫폼 연령 신호 포함

Automatic age assurance

기능 활성화

트리거 조건

`CHALLENGE_AGE_GATE_AGE_ASSURANCE` 응답 예시

챌린지 처리

플랫폼 연령 카테고리 API 사용

예시: Meta Horizon의 GetAgeCategory API 사용

생년월일 형식

기본 권한