Play Age Signals API 연동 가이드: Android 앱을 위한 v0.0.6
Kotlin 기반 Play Age Signals 0.0.6의 3가지 호출 방식, 모든 상태, tier 및 경계값에 대한 의사결정 표, 오류 처리, 0.0.3 및 0.0.4에서의 마이그레이션, 테스트와 자체 연령 확인 시작 방법.

요약
현재 Play Age Signals API를 연동하려면 com.google.android.play:age-signals:0.0.6을 추가하고, Activity와 함께 requestAgeSignalsAccess를 호출하며, 상태가 SHARED인 경우에만 checkAgeSignals를 호출하십시오.[1][2]
ageLower에서 연령을 확인하십시오. 티어는 연령이 어떻게 확정되었는지를 나타내며, null은 결코 성인이 아닙니다.- 가이드에는 API 23으로 안내되어 있으나, 0.0.6 라이브러리 매니페스트는 minSdk 24를 선언합니다.[1][11]
- 신호는 앱 내에 유지됩니다. 자체 연령 확인이 필요한 경우 신호 없이 시작하십시오.
이 문서는 Play Age Signals API에 대한 엔지니어링 가이드입니다. Android부터 시작해 Flutter, React Native, Expo, Unity를 다룹니다. 적용 대상과 2027년 1월부터 시작되는 사항에 대해서는 Google Play Age Signals API: 2027년 1월의 변경 사항 문서를 참고하십시오. Google은 API를 제공할 뿐 호출을 강제하지 않으며, 법률에 의해 의무화될 수 있습니다.
아래의 모든 클래스, 메서드, enum은 2026년 11월 22일 기준 Google 페이지 및 배포된 0.0.6 라이브러리를 바탕으로 검증되었습니다. 신호용 Kotlin 코드는 이에 맞춰 정상 컴파일됩니다.
필요 사항
이 API는 기기의 Play Store 앱을 통해 휴대전화, 폴더블, 태블릿에서 실행됩니다.[1][5]
minSdk를 24로 설정하십시오(경고 참조).- Google Play를 통해 배포하십시오. 이용약관에 따라 이 API는 Google Play가 업데이트하는 앱으로 제한됩니다.[5]
- Play Console에서 연령 신호 페이지를 여십시오. 맞춤 연령, 중대한 변경사항 및 철회된 승인이 해당 페이지에서 관리됩니다.[3][8][9]
- Play의 데이터 보안 양식은 직접 작성하십시오. Google은 클라이언트 라이브러리가 데이터를 수집하지 않으며 양식 작성은 귀하의 결정 사항이라고 명시합니다.[5]
주의 사항
Google의 설정 페이지에는 Android 6.0, API 레벨 23으로 안내되어 있습니다.[1] 0.0.6 라이브러리 내부의 매니페스트는 minSdkVersion 24를 선언하며, 0.0.3 및 0.0.4는 23을 선언했습니다.[11] minSdk 23으로 설정된 앱은 업그레이드 후 매니페스트 병합 단계에서 빌드가 중단될 수 있습니다. 24로 올리는 것이 간단한 해결책입니다.
- 2026년 2월0.0.3단일 호출,
userStatus, DECLARED 추가. - 2026년 7월0.0.4두 번의 호출, 티어가
userStatus를 대체. - 2026년 11월0.0.6전 세계 적용,
getApplicableAgeFeatures추가. - 2026년 12월 11일모든 사용자모든 사용자에게 응답이 제공되는 Google의 예정일.
Google의 릴리스 노트 및 배너에 따른 라이브러리 버전입니다.[2][4] 해당 날짜 전까지는 일부 사용자에게 응답이 없을 수 있습니다.
라이브러리 추가
의존성은 하나입니다.[1] 테스트용 모의 매니저도 동일한 아티팩트에 포함되어 있습니다.[11]
dependencies {
implementation("com.google.android.play:age-signals:0.0.6")
}
1getApplicableAgeFeatures(선택 사항)
해당 사용자에 대해 공유가 필수인지 여부.
2requestAgeSignalsAccess
Google Play 자체 프롬프트가 표시될 수 있습니다.
상태가 SHARED인지 확인
3checkAgeSignals
경계값, 소스, 변경 상태를 읽습니다.
Google에서 연령 정보를 제공하지 않음
연령에 적합한 기본값을 사용하십시오.
0.0.6에서의 호출 순서입니다.[2]
1단계: 이 사용자에 대해 공유가 필수인지 확인
호출은 선택 사항입니다.[2] features()는 앱 스토어가 연령 정보를 공유하도록 법률로 규정된 지역의 사용자에 대해서만 MANDATORY_SHARING을 포함하며, 그 외 모든 사용자에게는 비어 있습니다.[2]
val manager = AgeSignalsManagerFactory.create(applicationContext)
manager.getApplicableAgeFeatures(ApplicableAgeFeaturesRequest.builder().build())
.addOnSuccessListener { result ->
val mandatory = ApplicableAgeFeature.MANDATORY_SHARING in result.features()
// Use it to word your own screen. It is not an age.
}
.addOnFailureListener { error -> handleAgeSignalsError(error) }
참고
필수라는 것은 사용자의 공유가 필수임을 의미합니다. 연령이 어떻게 설정되었는지는 나타내지 않습니다. Google은 TIER_A, TIER_B, TIER_C, TIER_D와 함께 MANDATORY_SHARING을 문서화하고 있습니다.[3]
2단계: 액세스 요청
Google 설명서에는 requestAgeSignalsAccess(Activity)로 표기되어 있습니다. 이 메서드는 Activity를 전달하는 AgeSignalsAccessRequest를 인수로 받습니다.[2] 프롬프트가 표시되어도 적절한 위치에서 호출하십시오.
val request = AgeSignalsAccessRequest.builder()
.setActivity(this)
.build()
manager.requestAgeSignalsAccess(request)
.addOnSuccessListener { access ->
when (access.ageSignalsStatus()) {
AgeSignalsStatus.SHARED -> readSignals(manager)
AgeSignalsStatus.NOT_SHARED -> applyGate(AgeGate.NoSignal)
AgeSignalsStatus.VERIFICATION_REQUIRED -> applyGate(AgeGate.VerifyInPlay)
else -> applyGate(AgeGate.NoSignal) // UNSPECIFIED or null
}
}
.addOnFailureListener { error -> handleAgeSignalsError(error) }
사용자에게 표시되는 화면은 지역 및 설정에 따라 다릅니다.[2]
| 사용자 | 프롬프트 | 상태 |
|---|---|---|
| 스토어가 인증된 연령을 제공해야 하는 미국 주, 인증됨 또는 감독 대상 | 없음 | SHARED |
| 동일 지역, 아직 인증되지 않음 | 앱 내 없음, Play에서 처리 | VERIFICATION_REQUIRED |
| 그 외 지역, 공유 전 확인(기본값[14]) | Play의 인앱 프롬프트 | SHARED 또는 NOT_SHARED |
| 그 외 지역, 항상 공유 | 없음 | SHARED |
| 그 외 지역, 공유 안 함 | 없음 | NOT_SHARED |
| 그 외 지역, 감독 대상 | 없음. 부모가 Family Link에서 결정합니다 | SHARED 또는 NOT_SHARED |
사용자가 프롬프트를 몇 번 닫으면 Play에서 표시를 중단하므로 루프로 호출하지 마십시오.[2] 공유가 의무인 지역에서는 설정이 항상 공유로 고정됩니다.[14]
3단계: 결과 읽기
모든 필드는 null이 될 수 있으므로 한 번 변환하여 앱 내에서 단일 유형으로 유지하십시오. 이 매핑은 경계값에서만 연령을 읽습니다.
sealed interface AgeGate {
data object NoSignal : AgeGate
data object VerifyInPlay : AgeGate
data class Range(
val lower: Int,
val upper: Int?, // null = top band, not "adult"
val source: Int?, // AgeRangeSource.TIER_A to TIER_D
val changeStatus: Int? // SignificantChangeStatus
) : AgeGate {
fun isAtLeast(age: Int) = lower >= age
}
}
fun toAgeGate(r: AgeSignalsResult): AgeGate {
val lower: Int = r.ageLower() ?: return AgeGate.NoSignal
return AgeGate.Range(
lower, r.ageUpper(), r.ageRangeSource(), r.significantChangeStatus()
)
}
private fun readSignals(manager: AgeSignalsManager) {
manager.checkAgeSignals(AgeSignalsRequest.builder().build())
.addOnSuccessListener { result -> applyGate(toAgeGate(result)) }
.addOnFailureListener { error -> handleAgeSignalsError(error) }
}
status, source, change 상수는 정수이며 0은 UNSPECIFIED입니다.[10][11] else 분기에서 처리하십시오. 값이 변경될 수 있으므로 Google의 0.0.3 가이드에서는 앱이 열릴 때 새로 요청할 것을 권장했습니다.[12] 사용자가 나중에 공유를 끌 수도 있습니다.[14]
참고
해당 가이드는 인증된 기기의 변조되지 않은 빌드에서 호출이 이루어지도록 Play Integrity API를 함께 호출할 것도 권장합니다.[12] 이 신호는 클라이언트 측 응답입니다. 수정된 클라이언트가 서버로 전송하는 연령대를 신뢰하지 마십시오.
의사결정 표: 상태 x 소스 x 경계값
기본 범위는 0-12, 13-15, 16-17 및 18+입니다.[3] 마지막 열은 Google이 아닌 당사의 엔지니어링 권장 사항입니다.
| 상태 | 소스 | 하한 / 상한 | 의미 | 코드 동작 |
|---|---|---|---|---|
| 예외 | 없음 | 없음 | 응답 없음[7] | 재시도 가능한 경우 재시도 후 신호 없음 처리 |
NOT_SHARED | null | null / null | 사용자 또는 부모가 공유에 동의하지 않음[2][3] | 연령에 적합한 기본값 적용, 프롬프트를 반복 표시하지 않음 |
VERIFICATION_REQUIRED | null | null / null | 미인증 상태, 인증 및 공유가 의무적인 지역[2][3] | Play Store로 안내하고 기본값 유지 |
SHARED | TIER_A | 13 / 15 | 사용자가 Google에 연령을 제공했으며, Google이 이를 확인했을 수도 있고 확인하지 않았을 수도 있음[3] | 연령대 적용 |
SHARED | TIER_A | 18 / null | 동일함, 성인 연령대[3] | 이를 적용하고, 법률 또는 리스크 관리상 필요한 경우에만 확인 추가 |
SHARED | TIER_B | 13 / 15 | 부모 또는 보호자가 관리하는 연령[3] | 연령대를 적용하고 변경 상태 확인 |
SHARED | TIER_C | 18 / null | 신용카드, 이메일, 셀카, 정부 신분증 또는 납세자 ID로 평가됨[3] | 연령대 적용 |
SHARED | TIER_D | 18 / null | 정부 신분증과 셀카, 또는 디지털 ID[3] | 연령대 적용 |
SHARED | 모든 값 | null / 모든 값 | Google의 응답 테이블에 없음 | 신호 없음으로 처리 |
대부분의 실수는 세 가지 해석에서 발생합니다.
- TIER_A는 “미인증”이 아닙니다. 디지털 ID로 인증했으나 자발적으로 공유하는 성인도 TIER_A로 전달됩니다.[3] TIER_C 및 TIER_D는 텍사스와 같이 연령 확인이 의무화된 지역에서만 반환됩니다.[3] 클래스 레퍼런스에서는 TIER_A를 “자체 신고”로 표기하지만, 응답 가이드는 더 신중하게 다룹니다.[3][10]
- TIER_B는 연령이 아닙니다. 누가 관리하는지를 나타냅니다. 경계값을 확인하십시오.
- null 경계값은 인증된 성인을 의미하지 않습니다. Google의 Java 샘플 주석에서는 이를 시사하지만, Kotlin 샘플에서는 사용자가 공유하지 않는 상태라고 명시하며 응답 테이블도 Kotlin과 일치합니다.[2][3]
추가 확인을 멈춰야 하는 시점
반환된 연령 구간이 필요한 요건을 충족하고 법률이나 위험 측면에서 추가 정보를 요구하지 않는다면 확인을 중단하십시오. 모든 사용자를 대상으로 2차 확인을 수행하는 것은 데이터 최소화 원칙에 부합하기 어렵습니다. 캘리포니아주에서는 명확하고 설득력 있는 내부 정보를 보유하고 있지 않은 한 해당 신호가 기본 지표로 인정됩니다.[15]
신호 없음으로 분기되는 경우 이후의 처리 방안은 NOT_SHARED, TIER_A 또는 무응답 시 대처 방법을 참조하십시오.
맞춤 최소 연령
맞춤 연령 범위 탭에서 최소 2년 간격의 최소 연령을 최대 3개까지 입력할 수 있으며, 연 1회 변경 가능합니다. 이는 기본 응답보다 우선 적용됩니다.[3]
| 설정된 최소 연령 | 반환된 범위 | 최상위 구간 |
|---|---|---|
| 없음 (기본값) | 0-12, 13-15, 16-17, 18+ | 18 / null |
| 15 | 0-14, 15+ | 15 / null |
| 13, 17 | 0-12, 13-16, 17+ | 17 / null |
| 11, 13, 15 | 0-10, 11-12, 13-14, 15+ | 15 / null |
Google 응답 가이드의 예시입니다.[3]
예시
13과 17을 설정하면 25세 사용자에 대해서도 17세 사용자와 동일하게 17 / null이 반환됩니다. null인 ageUpper를 성인으로 처리하는 코드는 17세 사용자의 18세 이상 기능 접근을 허용하게 되므로, 18세를 기준으로 차단하는 경우 목록에 18을 유지해야 합니다. 문서화된 범위 한도는 18세까지입니다[3]. 이 API는 21세 기준 차단에는 대응할 수 없습니다.
중대한 변경 및 철회된 승인
두 기능 모두 감독 대상 사용자를 위한 기능입니다. 특정 변경이 중대한 변경에 해당하는지 여부는 관련 법률을 바탕으로 개발사가 직접 판단해야 하며 Play가 결정하지 않습니다[8]. 주별 규정은 App Store Accountability Acts에 설명되어 있습니다.
Play에 알림
중대한 변경
- 최대 3건의 변경, 최대 90일 전, 2일을 초과하는 간격
- 영어 설명이 필요하며, 부모에게 그대로 표시됩니다
significantChangeStatus는 APPROVED, PENDING 또는 DECLINED입니다- 앱은 변경된 기능을 제한해야 합니다
누적 적용: 한 번의 승인으로 대기 중인 모든 변경 사항이 적용됩니다[8]
Play에서 알림을 보냅니다
철회된 승인
installId는 사용자 및 기기별로 지정되며, 재설정 시 유지되지 않습니다- 이 목적으로만 백엔드에 저장할 수 있습니다
- 철회된 ID는 Play Console에 CSV 형태로 표시됩니다
- 각 항목은 90일 후에 삭제되므로 정기적으로 다운로드하십시오
하나의 ID가 두 번 이상 나타날 수 있습니다[9]
PENDING 및 DECLINED 상태에서는 앱 전체가 아닌 변경된 기능만 차단하십시오. 감독 대상이 아닌 계정과 기록된 변경 사항이 없는 감독 대상 계정의 경우 상태는 null입니다.[3]
오류 및 미지원 기기
실패는 AgeSignalsException으로 전달됩니다. Google은 최대 시도 횟수를 두고 재시도할 것을 권장합니다.[7]
// -8 (CLIENT_TRANSIENT_ERROR) to -1 (API_NOT_AVAILABLE) are marked retryable
private val RETRYABLE =
AgeSignalsErrorCode.CLIENT_TRANSIENT_ERROR..AgeSignalsErrorCode.API_NOT_AVAILABLE
private var attempts = 0
fun handleAgeSignalsError(e: Exception) {
val code = (e as? AgeSignalsException)?.errorCode
if (code in RETRYABLE && attempts++ < 3) retryLater()
else applyGate(AgeGate.NoSignal)
}
| 코드 | 상수 | 재시도 | 조치 |
|---|---|---|---|
| -1, -6 | API_NOT_AVAILABLE, PLAY_STORE_VERSION_OUTDATED | 예 | Play Store 업데이트 요청 |
| -2 | PLAY_STORE_NOT_FOUND | 예 | Play Store 설치 또는 활성화 요청 |
| -3 | NETWORK_ERROR | 예 | 네트워크 연결 확인 요청 |
| -4, -7 | PLAY_SERVICES_NOT_FOUND, PLAY_SERVICES_VERSION_OUTDATED | 예 | Play Services 설치, 활성화 또는 업데이트 요청 |
| -5 | CANNOT_BIND_TO_SERVICE | 예 | 지수 백오프 적용 후 Play Store 업데이트 |
| -8 | CLIENT_TRANSIENT_ERROR | 예 | 제한된 횟수로 재시도 후 나중에 다시 시도 |
| -9 | APP_NOT_OWNED | 아니요 | Google Play를 통해 설치되지 않음: 사이드로드 또는 다른 스토어 |
| -10 | SDK_VERSION_OUTDATED | 아니요 | 최신 라이브러리 배포 |
| -11 | DEVICE_NOT_SUPPORTED | 아니요 | 지원되지 않는 기기 유형. 0.0.6에서 새로 추가됨[4] |
| -100 | INTERNAL_ERROR | 아니요 | Google 문서는 여전히 횟수 제한 재시도를 권장하지만 위 코드는 이를 재시도하지 않음 |
Google의 오류 코드 참조.[7] 오류는 연령이 아닙니다. 기본 환경으로 폴백하십시오.
0.0.3 및 0.0.4에서 마이그레이션
버전 0.0.3은 여전히 응답을 반환하지만 업데이트를 받지 않습니다.[12] 이 버전에서 전환하려면 읽기 경로를 다시 작성해야 합니다. 0.0.4에서의 전환은 간단합니다.
| 코드 내 | 0.0.6 기준 | 이전 |
|---|---|---|
checkAgeSignals 단독 호출 | requestAgeSignalsAccess 먼저 호출[4] | 0.0.3 |
userStatus() | 제거됨: ageRangeSource() 및 significantChangeStatus()[4] | 0.0.3 |
VERIFIED | TIER_C 또는 TIER_D (당사 해석) | 0.0.3 |
DECLARED | TIER_A 또는 부모가 관리하는 경우 TIER_B (당사 해석) | 0.0.3 |
SUPERVISED | TIER_B (당사 해석) | 0.0.3 |
SUPERVISED_APPROVAL_PENDING, SUPERVISED_APPROVAL_DENIED | PENDING 또는 DECLINED 상태의 TIER_B (당사 해석) | 0.0.3 |
UNKNOWN, null | 액세스 상태: VERIFICATION_REQUIRED 또는 NOT_SHARED (당사 해석) | 0.0.3 |
mostRecentApprovalDate() | significantChangeApprovalDate()[4] | 0.0.3 |
| 두 가지 호출, 티어 | 변경 없음. 유용한 경우 getApplicableAgeFeatures 추가[4] | 0.0.4 |
| 오류 처리 | DEVICE_NOT_SUPPORTED 추가[4] | 모두 |
minSdk 23 | 라이브러리는 24를 선언함[11] | 모두 |
Google은 값 대 값 매핑을 공개하지 않습니다. "당사 해석"으로 표시된 행은 두 정의를 비교하여 도출한 결과입니다.[3][12]
주의 사항
기존 AgeSignalsVerificationStatus 상수는 0.0.6에도 여전히 포함되어 있어 userStatus()가 존재하지 않아도 import 문은 컴파일됩니다.[11] 0.0.3에서 VERIFIED는 0이었으나, 0.0.6에서는 0이 UNSPECIFIED입니다.[10][11] 업그레이드 시 캐시된 정수 값을 삭제하십시오.
FakeAgeSignalsManager 및 라이선스 테스터로 테스트
FakeAgeSignalsManager는 Play Store와 통신하지 않습니다. 레퍼런스상 단위 테스트 및 초기 개발용으로 제한됩니다.[32] 교체할 수 있도록 매니저를 주입하십시오.
val fake = FakeAgeSignalsManager()
// Sharing is mandatory for this user
fake.setNextApplicableAgeFeaturesResult(
ApplicableAgeFeaturesResult.builder()
.setFeatures(setOf(ApplicableAgeFeature.MANDATORY_SHARING))
.build()
)
// Verification still pending in Play
fake.setNextAgeSignalsAccessResult(
AgeSignalsAccessResult.builder()
.setAgeSignalsStatus(AgeSignalsStatus.VERIFICATION_REQUIRED)
.build()
)
// Supervised 13 to 15, change waiting for the parent
fake.setNextAgeSignalsResult(
AgeSignalsResult.builder()
.setAgeRangeSource(AgeRangeSource.TIER_B)
.setAgeLower(13)
.setAgeUpper(15)
.setSignificantChangeStatus(SignificantChangeStatus.PENDING)
.setInstallId("fake_install_id_123")
.build()
)
// Fails checkAgeSignals
fake.setNextAgeSignalsException(
AgeSignalsException(AgeSignalsErrorCode.NETWORK_ERROR)
)
- 각 상태, 미성년자 구간, 성인 구간, null 경계값, 그리고 호출별 오류 1건씩을 테스트에 포함하십시오(
setNextRequestAgeSignalsAccessException및setNextApplicableAgeFeaturesException은 나머지 두 호출을 실패시킵니다). - 라이선스 테스터로 실제 호출을 실행하십시오. 일반적으로 Play를 통해 업데이트되지 않은 앱은
APP_NOT_OWNED를 받지만, 테스터는 디버그 빌드를 사이드로드할 수 있습니다.[6] - 패키지 이름을 Play 앱과 동일하게 유지하고 테스터 계정으로 로그인하십시오.[6]
Flutter, React Native, Expo 및 Unity
이들은 Google의 패키지가 아닌 커뮤니티 또는 프레임워크 패키지이며, 목록에 기재되었다고 해서 추천을 의미하지는 않습니다. 출시 전에 라이브러리 버전을 확인하십시오.
| 스택 | 확인된 패키지 | 라이브러리 | 배포 전 확인 사항 |
|---|---|---|---|
| Expo | expo-age-range 58.0.3 | 0.0.4 | 웹 및 26 미만 iOS에서는 성인과 동일하게 lowerBound: 18을 반환합니다[17] |
| React Native | react-native-play-age-range-declaration 3.0.5 | 0.0.4 | 기타 스토어 및 Apple도 래핑합니다[19] |
| Flutter | age_range_signals 0.10.1 | 0.0.4 | 2회 호출 플로우, 라이선스 테스터 지원[18] |
| Unity | unity-play-age-signals | 0.0.4 | GPL-3.0; 콜백이 메인 스레드 외부에서 실행될 수 있습니다[20] |
2026년 11월 22일 각 패키지 페이지 또는 빌드 파일에서 확인한 내용입니다.[17][18][19][20] Unity 담당자는 2025년 12월에 Unity가 전용 플러그인을 출시하지 않을 것이라고 밝혔습니다.[21]
0.0.4 버전 패키지에는 getApplicableAgeFeatures 및 DEVICE_NOT_SUPPORTED가 없습니다. 해당 항목이 필요하다면 간단한 네이티브 브리지를 작성하십시오. Apple 측 내용은 Play Age Signals vs Apple Declared Age Range에서 비교합니다.
로그 기록, 공유, 프로파일링 금지
Google 약관은 해당 정보를 요청 앱 내에서 법률을 준수하는 연령에 적합한 경험을 제공하는 용도로 제한합니다.[5] 해당 정책은 법률에서 엄격히 요구하는 경우를 제외하고 광고, 분석, 프로파일링 및 제3자에 대한 데이터 판매, 공유 또는 이전을 금지합니다.[13]
- 연령대 구간, 티어 및
installId를 로그, 충돌 보고서, 분석 이벤트에 포함하지 마십시오. 이러한 도구는 대개 제3자 소유입니다. - 가능한 경우 원시 결과를 메모리에 유지하고, 티어 대신 기능 결정 사항을 저장하십시오.
- Didit을 포함하여 연령 확인 벤더에 신호를 첨부하지 마십시오.
- 캘리포니아주에서는 사용자에게 연령 정보 변경을 유도하지 말고, 해당 법률에서 요구하지 않는 목적으로 제3자와 신호를 공유하지 마십시오.[15]
- 모든 사용자를 대상으로 신호를 요청하기 전에 법률 자문을 구하십시오. 캘리포니아주 법은 자체 규정이나 다른 관련 법률에서 요구하지 않는 요청을 금지합니다.[15]
따라서 “Play Store를 방문하십시오”라는 메시지는 연령대를 의심하는 캘리포니아주 사용자가 아니라 VERIFICATION_REQUIRED에 해당합니다. Google의 지역별 페이지에는 2027년 1월부터 캘리포니아주와 브라질이 의무 적용 지역으로, 앨라배마주는 “세부 정보 곧 공개 예정”으로 표시되어 있습니다.[16] 캘리포니아주의 의무 사항은 디지털 연령 보증법 가이드에 나와 있습니다.
신호 수신 후: 자체 확인 시작
앱에서 확인이 필요하다고 판단하면, 요청에는 워크플로와 사용자 ID만 포함되며 Google의 응답은 절대 포함되지 않습니다. API 키가 기기에 노출되어서는 안 되므로 서버에서 Didit을 호출하십시오.
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "YOUR_AGE_WORKFLOW_ID",
"vendor_data": "user-42"
}'
201 응답에는 session_id, session_token, url이 포함됩니다.[25] 토큰만 앱으로 전송한 후 SDK를 시작하십시오:[26]
// Once, in Application.onCreate: DiditSdk.initialize(this)
lifecycleScope.launch {
DiditSdk.state.collect { state ->
if (state is DiditSdkState.Ready) DiditSdk.launchVerificationUI(this@MainActivity)
}
}
DiditSdk.startVerification(token = sessionToken) { result ->
when (result) {
is VerificationResult.Completed -> refreshAgeDecision() // asks your server
is VerificationResult.Cancelled -> keepSafeDefault()
is VerificationResult.Failed -> keepSafeDefault()
}
}
SDK 결과는 인터페이스용입니다. 서명된 status.updated 웹훅에서 결정을 가져오거나, 서버에서 GET /v3/session/{sessionId}/decision/을 조회하십시오.[25][29] 취소 및 실패 시에는 안전한 기본값을 유지하십시오.
한계 파악
신호로 충분한 경우에는 이 단계를 건너뛰십시오. 자체 확인이 항상 우선 적용되는 것은 아닙니다. 2027년부터 의무가 시행되는 앨라배마주와 유타주 법률은 보호 대상에 가장 낮은 연령 범주를 적용하고, 브라질은 더 보호적인 대안을 적용하므로, 이들 지역에서는 확인을 통해 제한을 강화할 수만 있습니다.[22][23][24] 일리노이주, 텍사스주 또는 콜로라도주 법률의 적용을 받는 사용자는 셀카 촬영 전에 생체 인식 동의 단계가 필요하며, 이는 네이티브 SDK 4.10.0 이상에서 표시할 수 있습니다.[28] 귀하의 앱에 적용되는 규칙을 법률 자문과 함께 확인하십시오.
신호 수신 후 Didit이 지원하는 방식
Didit Age Estimation은 셀카를 통해 동일한 단계에서 라이브니스와 함께 연령을 추정하며, 해당 인물이 누구인지는 식별하지 않습니다. 워크플로는 직접 설정한 경계 구간을 문서 검사로 전달할 수 있습니다.[27] Age Estimation의 비용은 호출당 $0.10입니다. 가격 정책을 확인하십시오.

Didit 콘솔의 연령 추정 결과(샘플 데이터): 문서상의 연령 옆에 표시된 셀카 추정치.
Android, iOS, React Native, Flutter용 네이티브 SDK가 제공됩니다. Unity 및 기타 엔진의 경우 문서화된 경로는 WebView 연동입니다.[31] Google Play 외부 환경은 연령 확인 API: 앱, 웹 및 스토어 및 연령 확인 솔루션 페이지에서 다룹니다.
Didit이 제공하는 기능
- 셀카, 라이브니스 및 선택적 문서 단계를 포함한 호스팅 연령 확인
- 최소 13세부터 개인정보 없이 연령에 대한 예 또는 아니오 결정만 반환하는 ISO/IEC 27566-1 워크플로 옵션[27]
- 보유 기간 설정, 반환 데이터 전환 스위치 및 삭제 호출[30]
직접 관리해야 하는 사항
- Play Age Signals 호출 및 그 결과
- 적용되는 법률 및 확인 수행 필요 여부
- 연령 적합 기본 설정 및 최종 접근 결정
Didit에는 Play Age Signals 커넥터가 없습니다. 신호는 앱 내에 머뭅니다.
핵심 요약
- 0.0.6을 사용하십시오. 선택적 기능 호출, 액세스 요청 후
SHARED인 경우에만checkAgeSignals를 실행합니다. ageLower를 기준으로 제한하십시오.ageUpper가 null이면 최상위 구간을 의미하며, 맞춤 연령을 통해 이를 18세 미만으로 낮출 수 있습니다.- Null 경계값,
UNSPECIFIED및 오류는 신호가 없음을 의미하며, 절대 성인을 뜻하지 않습니다. - 0.0.6 매니페스트는 minSdk 24를 선언합니다.
- 신호는 앱 내에 유지하고, 자체적인 확인은 해당 신호 없이 시작하십시오.
자주 묻는 질문
어떤 버전의 Play Age Signals API를 사용해야 합니까?
0.0.6을 사용하십시오. 전 세계에서 사용 가능한 최신 버전이며, Google에 따르면 2026년 12월 11일까지 모든 사용자에 대해 응답을 반환할 예정입니다. 그동안 0.0.4는 일부 지역에서 응답을 계속 반환합니다.[2]
getApplicableAgeFeatures를 호출해야 합니까?
아닙니다. Google은 이를 선택 사항으로 지정했습니다. 공유가 의무적인 사용자를 위해 자체 화면 구성을 달리해야 하는 경우 호출하십시오.[2]
NOT_SHARED와 VERIFICATION_REQUIRED의 차이점은 무엇입니까?
NOT_SHARED는 사용자 또는 보호자가 공유에 동의하지 않아 앱이 연령 신호를 수신하지 못함을 의미합니다. VERIFICATION_REQUIRED는 확인과 공유가 모두 의무적인 지역에서 연령이 확인되지 않았음을 의미하며, Google은 사용자에게 Play Store 방문을 요청하도록 안내합니다.[2]
두 경계값이 모두 null인 이유는 무엇입니까?
응답 레퍼런스는 상태가 NOT_SHARED 또는 VERIFICATION_REQUIRED일 때 null 경계값을 제시합니다.[3] null 경계값은 신호가 없는 것으로 취급해야 하며, 절대 성인으로 간주해서는 안 됩니다.
성인의 경우 ageUpper가 왜 null인가요?
최상위 구간의 상한이 열려 있기 때문입니다. 즉 18+는 ageLower 18과 ageUpper null을 반환합니다.[3] 맞춤 연령을 적용하면 최상위 구간이 더 낮게 시작할 수 있으므로, ageLower를 자체 최소 연령과 비교하십시오.
자체 연령 범위를 설정할 수 있나요?
예, Play Console의 연령 신호 페이지에서 최소 2년 간격으로 최대 3개의 최소 연령을 설정할 수 있으며, 연 1회 변경 가능합니다. 이는 기본 연령 범위보다 우선 적용됩니다.[3]
법이 적용되기 전에 어떻게 테스트하나요?
FakeAgeSignalsManager를 사용하여 MANDATORY_SHARING을 포함한 모든 상태, 범위 또는 오류를 반환하도록 하십시오. 라이선스 테스터 계정을 사용하면 사이드로드된 디버그 빌드에서 라이브 API를 호출할 수 있습니다.[6]
Trusted Web Activity 또는 WebView에서 작동하나요?
웹 코드에서는 작동하지 않습니다. 이는 Activity와 함께 호출되는 Android 라이브러리이며, 당사가 확인한 Google 문서에는 웹 인터페이스가 명시되어 있지 않습니다. 래퍼 앱에는 자체 네이티브 코드가 필요하며, Google 약관은 해당 정보를 요청 앱으로 제한합니다.[2][5]
Unity, Flutter 또는 React Native 플러그인이 있나요?
커뮤니티 및 프레임워크 패키지가 존재합니다. 2026년 11월 22일에 확인한 패키지들은 0.0.4를 선언하고 있어 getApplicableAgeFeatures가 누락되어 있습니다. Unity 담당자는 2025년 12월에 Unity가 전용 플러그인을 출시하지 않을 것이라고 밝혔습니다.[17][18][19][20][21]
결과를 자체 서버에 저장할 수 있나요?
Google 페이지에는 철회 통지를 위해 백엔드에 installId를 저장하는 내용이 명시되어 있습니다. 그 외의 경우 법적 의무에 필요한 최소한의 결과만 자체 시스템 내에 보관해야 하며, 법률에서 엄격히 요구하지 않는 한 분석, 광고 또는 타사 서비스에 저장해서는 안 됩니다.[9][13]
출처
- Use Play Age Signals API (beta), Android Developers, 2026년 11월 19일 업데이트.
- Request age signals, Android Developers, 2026년 11월 18일 업데이트.
- Understand age signals responses, Android Developers, 2026년 11월 18일 업데이트.
- Play Age Signals release notes, Android Developers, 2026년 11월 19일 업데이트.
- Play Age Signals overview and terms of service, Android Developers, 2026년 11월 18일 업데이트.
- Test your Play Age Signals API (beta) integration, Android Developers, 2026년 11월 19일 업데이트.
- Play Age Signals API error code reference, Android Developers, 2026년 11월 18일 업데이트.
- Notify Google Play of significant changes, Android Developers, 2026년 9월 4일 업데이트.
- Review revoked app approvals, Android Developers, 2026년 9월 4일 업데이트.
- AgeRangeSource reference, Android Developers, 2026년 11월 18일 업데이트.
- com.google.android.play:age-signals, Google Maven; 2026년 11월 22일 확인한 버전 0.0.3, 0.0.4, 0.0.6의 라이브러리 매니페스트 및 클래스.
- Use Play Age Signals API, version 0.0.3, Android Developers, 2026년 10월 23일 업데이트.
- Age Signals API and User Data policy, Google Play Console 고객센터.
- About age range sharing on Google Play, Google Play 고객센터.
- AB 1856, Chapter 184, Statutes of 2026, California Legislative Information; Civil Code 1798.500부터 1798.504까지 개정.
- Regional age-related protections on Play, Android Developers, 2026년 11월 18일 업데이트.
- Expo AgeRange, Expo 문서; 패키지 expo-age-range 58.0.3.
- age_range_signals, pub.dev, 2026년 10월 6일 버전 0.10.1.
- react-native-play-age-range-declaration, GitHub, 버전 3.0.5.
- unity-play-age-signals, GitHub, 2026년 8월 4일 업데이트됨.
- Play Age Signals API 지원, Unity Discussions, 2025년 12월 Unity 담당자 답변.
- Code of Alabama 8-19K-9 (HB 161), 앨라배마주 의회.
- Utah Code 13-76-202, 유타주 의회; 2027년 5월 6일부터 개발자 의무 적용.
- 2026년 3월 18일자 Decreto 12.880 제25조, Planalto, 브라질.
- 세션 생성, Didit 문서.
- Android SDK, Didit 문서.
- 연령 추정 개요, Didit 문서.
- 생체 인식 동의, Didit 문서.
- 웹훅, Didit 문서.
- 데이터 보존, Didit 문서.
- 네이티브 SDK 개요, Didit 문서.
- FakeAgeSignalsManager 레퍼런스, Android Developers, 2026년 11월 18일 업데이트됨.
세 가지 호출을 배포하고 표의 모든 항목을 테스트하며, Google 약관에 따라 신호를 앱 내에 유지하십시오. 신호로 확인할 수 없는 분기에는 자체 확인 절차로 연령 추정을 추가하십시오.