플랫폼 신호 세부 사항

이 페이지는 플랫폼 연령 신호의 구현 중심 참조 문서입니다. 클라이언트 또는 서버 측 통합에 직접 매핑할 수 있는 정확한 필드 형태, 엔드포인트 동작 및 예시가 필요할 때 사용하세요.

올바른 신호 형태 선택

플랫폼	기본 신호 유형	k-ID로 전송할 내용	연령 요건에 대해 확인됨?	참고 사항
Apple iOS	숫자 연령 범위	`ageLow`, `ageHigh`, 선택적 `declarationType`	예, 확인된 선언 유형에 대해	`category` 전송 금지
Google Play	숫자 연령 범위	`ageLow`, `ageHigh`, 선택적 `declarationType`	예, 확인된 선언 유형에 대해	`category` 전송 금지
Xbox	카테고리	`category`	아니오	k-ID가 플레이어의 관할권을 사용하여 카테고리 해석
Meta Horizon	카테고리	`category`	아니오	k-ID가 플레이어의 관할권을 사용하여 카테고리 해석
k-ID	이전 확인	`verificationId`, 선택적 `category` 또는 범위	예, 확인이 유효한 경우	`declarationType`은 서버 측에서 확인

팁

플랫폼이 이미 ageLow와 ageHigh를 제공하는 경우, 해당 값을 직접 전송하세요. POST /age-gate/get-platform-age-range는 카테고리 기반 플랫폼에서만 사용하세요。

플랫폼별 통합 가이드

Apple iOS

신호 얻는 방법: Age Range Service를 사용하여 플레이어의 연령 범위 및 선언 유형을 가져옵니다.

k-ID로 전송할 내용: name, ageLow, ageHigh, 선택적으로 declarationType.

확인된 선언 유형: paymentChecked, governmentIDChecked, guardianPaymentChecked, guardianGovernmentIDChecked

{
  "name": "apple-ios",
  "ageLow": 18,
  "ageHigh": 25,
  "declarationType": "governmentIDChecked"
}

Google Play

신호 얻는 방법: Play Age Signals API를 사용하여 플레이어의 연령 범위 및 userStatus를 가져옵니다.

k-ID로 전송할 내용: name, ageLow, ageHigh, 선택적으로 declarationType.

확인된 선언 유형: VERIFIED, SUPERVISED

{
  "name": "google-play",
  "ageLow": 13,
  "ageHigh": 17,
  "declarationType": "VERIFIED"
}

Xbox

신호 얻는 방법: XR-014와 XUserGetAgeGroup을 사용하여 플레이어의 연령 그룹을 가져옵니다.

k-ID로 전송할 내용: name 및 category.

허용되는 카테고리: child, teen, adult

k-ID가 해석하는 방법:

child = [0, digitalConsentAge - 1]
teen = [digitalConsentAge, civilAge - 1]
adult = [civilAge, 100]

Xbox 신호는 확인된 연령 권한에 대해 확인된 것으로 간주되지 않습니다.

{
  "name": "xbox",
  "category": "adult"
}

Meta Horizon

신호 얻는 방법: Get Age Category API를 사용하여 CH, TN 또는 AD를 가져옵니다.

k-ID로 전송할 내용: name 및 category.

허용되는 카테고리: CH, TN, AD

k-ID가 해석하는 방법:

CH = [10, digitalConsentAge - 1] (최소 연령 10세)
TN = [digitalConsentAge, civilAge - 1]
AD = [civilAge, 100]

일반적인 브라질 구성의 경우 CH=10-12, TN=13-17, AD=18+이 됩니다.

Meta Horizon 신호는 확인된 연령 권한에 대해 확인된 것으로 간주되지 않습니다.

{
  "name": "meta-horizon",
  "category": "TN"
}

k-ID

신호 얻는 방법: 이전에 완료된 k-ID 확인을 사용하고 해당 verificationId를 전달합니다.

k-ID로 전송할 내용: name: "k-id" 및 verificationId. 흐름에 필요한 경우 category 또는 ageLow와 ageHigh를 전송할 수도 있지만, 신호가 확인된 것으로 간주되는지는 확인 조회에서 결정됩니다.

서버 측 확인 검사: 신호는 다음 조건을 모두 충족할 때만 확인된 것으로 간주됩니다:

존재함
상태가 PASS
요청 제품과 동일한 조직에 속함

호출자가 제공한 declarationType 값은 k-id 신호에 대해 무시됩니다.

{
  "name": "k-id",
  "category": "adult",
  "verificationId": "a50f4f73-3c0c-4720-a8b3-ec57ccb0aa34"
}

참고

verificationId는 조직 내 제품당 하나의 활성 세션으로 제한됩니다. 동일한 확인은 동일한 조직 내 다른 제품에서 재사용할 수 있지만, 같은 제품의 여러 활성 세션에서는 사용할 수 없습니다。

API 참조

아래의 여섯 가지 엔드포인트는 플랫폼 연령 신호 통합과 가장 관련이 있습니다. 각 항목에는 언제, 왜 호출하는지 설명되어 있습니다. 전체 요청 및 응답 스키마는 API 참조 링크를 따르세요.

`GET /age-gate/get-requirements`

연령 게이트를 표시하기 전에 호출합니다. 플랫폼 신호 필드를 쿼리 매개변수(platformName, platformAgeLow, platformAgeHigh, platformCategory, platformDeclarationType, platformVerificationId)로 전달하여 입력을 수집하기 전에 k-ID가 신호를 반영할 수 있도록 합니다.

조치해야 할 주요 응답 필드:

shouldDisplay: 확인된 플랫폼 신호가 플레이어가 성인임을 증명할 때 false; 이것이 false이면 연령 게이트 UI를 건너뜀
ageAssuranceRequired: 모든 확인된 연령 권한이 이미 신호에 의해 충족된 경우에만 false
permissions: verifiedAgeThreshold가 있는 권한 목록; 모두 이미 충족된 경우에도 유용

`GET /age-gate/get-default-permissions`

세션을 생성하지 않고 권한 상태를 미리 보고 싶을 때 호출합니다. 전체 연령 게이트 흐름이 실행되기 전에 확인된 신호가 임계값 권한을 즉시 충족하는지 확인하는 데 유용합니다.

verifiedAgeThreshold가 있는 권한은 기본적으로 enabled: false
ageLow >= threshold인 확인된 신호는 해당 권한을 enabled: true로 설정
k-id 신호의 경우 선언 유형은 platformVerificationId에서 서버 측으로 확인됨

`GET /session/get`

check, VPC 또는 연령 보증 Challenge 이후 세션을 새로 고칩니다. 응답에는 확인된 플랫폼 신호(또는 완료된 연령 보증)가 세션에 기록된 경우 ageVerification 객체가 포함됩니다. 확인 소스를 이해하려면 ageVerification.platformName 및 ageVerification.declarationType을 확인하세요.

`POST /age-gate/check`

세션을 생성하거나 업데이트합니다. 요청 본문에 platformAgeSignal을 단독으로 또는 dateOfBirth, age 또는 kuid와 함께 전달합니다. k-ID는 두 가지 모두 있을 때 더 보수적인 연령을 사용합니다.

플랫폼 신호와 관련된 가능한 결과:

확인된 신호 + 연령이 임계값 충족: 세션에 ageVerification이 포함되고 권한이 enabled: true
신호가 있지만 확인되지 않음: ageVerification 없이 세션이 생성됨; 고위험 권한은 나중에 연령 보증이 필요
플레이어 연령이 임계값 미만: 권한이 managedBy: PROHIBITED; 연령 보증 복구 흐름 적용
연령 충돌: 연령 충돌 감지가 활성화되고 플랫폼 신호가 플레이어의 자체 신고 연령보다 더 어린 연령 카테고리를 나타낼 때 400 AGE_CONFLICT 반환

`POST /age-gate/get-platform-age-range`

플랫폼 카테고리 문자열을 특정 관할권의 구체적인 ageLow/ageHigh 쌍으로 변환합니다. 카테고리 기반 플랫폼(Xbox, Meta Horizon, k-ID)에만 필요합니다. 플랫폼이 이미 숫자 범위를 제공하는 경우 이 호출을 건너뛰고 값을 직접 전송하세요.

`POST /session/upgrade`

플레이어의 기존 세션에 대한 추가 권한을 요청합니다. 고위험 권한을 즉시 잠금 해제할 수 있는지 아니면 먼저 연령 보증 Challenge가 필요한지를 결정하는 엔드포인트입니다.

반환되는 Challenge 유형은 요청되는 내용에 따라 다릅니다:

시나리오	반환되는 `challenge.type`
권한이 `PLAYER` 관리	Challenge 없음: 권한이 즉시 활성화됨
권한이 `GUARDIAN` 관리	`CHALLENGE_SESSION_UPGRADE` (신뢰할 수 있는 성인 동의)
권한에 `verifiedAgeThreshold`가 있고 세션에 `ageVerification`이 없음	`CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE` (플레이어가 연령을 확인해야 함)
권한에 `verifiedAgeThreshold`가 있고 세션에 임계값을 충족하는 `ageVerification`이 이미 있음	Challenge 없음: 권한이 즉시 활성화됨

핵심 제약 사항: 단일 업그레이드 요청의 모든 권한은 같은 유형이어야 합니다. verifiedAgeThreshold가 있는 권한과 없는 권한을 한 번의 호출에 혼합하면 400: "Can't mix permissions with and without verifiedAgeThreshold"가 반환됩니다.

예시: 고위험 권한 요청 (연령 보증 트리거):

POST /api/v1/session/upgrade
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
  "requestedPermissions": [
    { "name": "loot-boxes-paid-gameplay-impacting" }
  ]
}

예시: 완료된 연령 이의 신청의 k-ID 신호를 전달하여 새 Challenge 없이 임계값을 직접 충족:

POST /api/v1/session/upgrade
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
  "requestedPermissions": [
    { "name": "loot-boxes-paid-gameplay-impacting" }
  ],
  "platformAgeSignal": {
    "name": "k-id",
    "verificationId": "a50f4f73-3c0c-4720-a8b3-ec57ccb0aa34"
  }
}

CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE Challenge가 반환되면, AgeKit+를 통해 연령 확인을 완료할 수 있도록 플레이어를 challenge.url로 안내합니다. Challenge가 통과되면 업데이트된 세션을 가져옵니다: 권한이 이제 enabled: true이고 세션에 ageVerification 객체가 있습니다.

유효성 검사 및 엣지 케이스

입력 유효성 검사

시나리오	결과
`name`이 없는 `platformAgeSignal`	400: "Platform name must be provided"
알 수 없는 플랫폼 이름	400: "Unknown platform name"
`category`가 있는 `apple-ios` 또는 `google-play`	400: "Platform must have age range specified"
`category`와 `ageLow`/`ageHigh` 모두 제공	400: "Provide either category or `ageLow` and `ageHigh`, not both"
`ageHigh` 없이 `ageLow`만 제공 (또는 그 반대)	400: "`ageLow` and `ageHigh` must both be provided"
`ageLow`가 `ageHigh`보다 큰 경우	400: 유효하지 않은 범위
`session/upgrade`에서 임계값과 비임계값 권한 혼합	400: "Can't mix permissions with and without verifiedAgeThreshold"

연령 충돌 매트릭스

기본 연령과 플랫폼 신호 모두 있는 경우:

플랫폼 연령 카테고리 \ 기본 연령 카테고리	기본: 미성년	기본: 청소년	기본: 성인
플랫폼: 미성년	충돌 없음	충돌	충돌
플랫폼: 청소년	충돌 없음	충돌 없음	충돌
플랫폼: 성인	충돌 없음	충돌 없음	충돌 없음

충돌은 플랫폼이 플레이어가 자체 신고한 연령 카테고리보다 더 어리다고 할 때만 발생합니다.

`k-id` 신호 보안 규칙

declarationType은 항상 verificationId에서 서버 측으로 확인됨
호출자가 제공한 declarationType은 무시됨
확인은 PASS여야 함
확인은 요청 제품과 동일한 조직에 속해야 함
유효한 verificationId 없이는 k-id 신호가 미확인으로 처리됨

보수적 기본값

shouldDisplay가 false이고 전송할 플랫폼 신호가 없는 경우, age: 1과 함께 POST /age-gate/check 호출
플랫폼 신호와 기본 연령이 다르지만 충돌하지 않으면 k-ID가 낮은 연령 사용
확인된 연령 권한은 실제로 충족될 때까지 기본적으로 enabled: false

올바른 신호 형태 선택​

플랫폼별 통합 가이드​

Apple iOS​

Google Play​

Xbox​

Meta Horizon​

k-ID​

API 참조​

GET /age-gate/get-requirements​

GET /age-gate/get-default-permissions​

GET /session/get​

POST /age-gate/check​

POST /age-gate/get-platform-age-range​

POST /session/upgrade​

유효성 검사 및 엣지 케이스​

입력 유효성 검사​

연령 충돌 매트릭스​

k-id 신호 보안 규칙​

보수적 기본값​