미성년자 보호 법안 대응

Hive SDK에서는 미성년자 보호를 위한 앱스토어 책임법과 브라질 ECA에 대응하여 사용자 연령을 확인할 수 있는 Age Range 모듈을 제공합니다. 사용자 연령 확인을 의무화하는 연령 확인 법안 시행에 따라 스토어를 통해 앱을 배포하는 개발자는 Age Range 모듈을 적용하여 사용자 연령 범위를 확인하고 보호자 승인을 요청할 수 있습니다.

Age Range 동작 개요¶

Age Range 모듈은 getAgeRange API를 호출하여 사용자 연령 범위와 상태를 확인합니다. 응답 결과에 따라 국가별 정책에 맞는 콘텐츠를 제공하거나, 필요한 경우 showAgeRangeUpdatePermission API를 호출하여 보호자 승인을 요청합니다.

사용 시점¶

Age Range 모듈은 사용자 연령 확인 법안이 시행된 국가에서만 적용합니다.

Note

Hive SDK v4 26.0.1(Android/iOS)부터 제공합니다.
Google Play는 Hive SDK v4 26.7.0부터 Google Play Age Signals 라이브러리 0.0.4를 사용합니다. 이전 버전과 응답 필드 및 사용자 상태 산출 방식이 달라졌습니다. 자세한 내용은 getAgeRange API 응답 데이터를 참조하세요.
법안이 시행되지 않은 국가에서는 Age Range 모듈을 적용하지 않아도 됩니다.

Warning

Google Play Age Signals 라이브러리 0.0.3은 2026년 10월 31일 이후 사용할 수 없습니다. Google Play로 배포하며 Age Range 모듈을 사용하는 앱은 Hive SDK v4 26.7.0 이상으로 업데이트해야 합니다.

Warning

법안 시행 전에는 getAgeRange 호출 시 정상적인 사용자 상태를 반환하지 않습니다.

연령 확인 법안 시행 전까지는 에러 응답을 수신할 수 있습니다.
Apple은 샌드박스 테스트 환경을 제공합니다. 관련하여 자세한 내용은 Apple 공식 공지문을 참조하세요.
연령 확인 법안 시행 전까지는 Age Range 모듈을 추가하지 않아도 무방하며, 추가하여 호출하는 경우에도 PENDING 혹은 DENIED와 같은 명확한 동작 에러 응답 외에 나머지 에러는 무시할 수 있습니다.
법안 시행 후에는 사용자 연령 및 상태 정보를 정상적으로 수신할 수 있습니다.

iOS 요구 사항¶

iOS에서 사용자 연령 범위 확인을 진행하려면 아래의 조건을 충족해야 합니다.

Xcode 26.2 이상
iOS 26.2 이상에서 기능 제공

Age Range 처리 흐름¶

OS별 구현 플로우¶

Android
- Google Play (Hive SDK v4 26.7.0 이상)
- Amazon Appstore, Samsung Galaxy Store, Google Play (Hive SDK v4 26.7.0 미만)
iOS
- Apple App Store

Note

Google Play는 브라질 ECA를 지원합니다. Hive SDK v4 26.7.0부터 Google Play는 DECLARED 상태를 반환하지 않습니다. 브라질과 같이 연령 정보 공유가 사용자·보호자의 선택에 기반하는 지역에서도 다른 지역과 동일한 상태값을 반환하며, 사용자가 직접 신고한 연령인지 여부는 ageRangeSource로 확인합니다.
Apple App Store는 브라질 ECA를 지원합니다. 법안 적용 대상인 경우 사용자의 연령 정보를 직접 제공하며, 연령 정보를 확인할 수 없는 경우 REQUIRED 상태를 반환합니다.
Amazon Appstore 및 Samsung Galaxy Store는 브라질 ECA를 지원하지 않으므로 브라질 관련 응답을 반환하지 않습니다.
Google Play의 응답에는 국가 및 관할 지역 정보가 포함되지 않습니다. 지역별로 다르게 대응해야 하는 경우 앱에서 Configuration.hiveCountry로 국가를 직접 확인해야 합니다. 이 값은 접속 IP를 기준으로 하므로 Google Play 계정에 설정된 국가와 다를 수 있습니다.
Google Play 구현 플로우의 SUPERVISED (승인 절차 미완료 포함)은 보호자 승인을 받지 못한 상태를 뜻하지 않습니다. SUPERVISED는 추가 승인이 필요하지 않은 미성년자 상태이며, 승인이 필요한 상태는 SUPERVISED_APPROVAL_PENDING과 SUPERVISED_APPROVAL_DENIED로 따로 반환됩니다.
본 가이드에서는 앱스토어 책임법에 대응하여 보호자 동의가 확인되지 않는 경우에는 앱에 진입할 수 없는 것으로 안내합니다. 다만, 실제 동작 방식은 각 앱의 서비스 정책 및 운영 정책에 따라 일부 다르게 적용될 수 있습니다.

국가별 처리 예시¶

적용 국가	주요 `userStatus`	앱 처리
연령 확인 법안 미시행 국가	`UNKNOWN`	별도 처리 없이 계속 진행합니다. 다만 브라질에 서비스하는 앱은 `UNKNOWN`이 브라질 사용자에게서 온 것일 수 있으므로, `UNKNOWN` 상태 판별에 따라 국가를 먼저 확인하세요.
미국	`VERIFIED`, `SUPERVISED`, `SUPERVISED_APPROVAL_PENDING`, `SUPERVISED_APPROVAL_DENIED`	사용자 연령 범위를 확인하여 연령에 맞는 콘텐츠를 제공합니다. `SUPERVISED` 상태에서 앱 내 중요한 변경 사항이 발생하면 보호자 승인을 요청합니다. Apple App Store는 `showAgeRangeUpdatePermission` API로, Android 스토어는 각 개발자 콘솔로 알립니다. 보호자 승인 진행 상태(`SUPERVISED_APPROVAL_PENDING`, `SUPERVISED_APPROVAL_DENIED`)는 앱 서비스 정책에 따라 기능 또는 콘텐츠를 제한할 수 있습니다.
브라질	`VERIFIED`, `SUPERVISED`, `UNKNOWN`, `REQUIRED`	사용자 연령 범위를 확인하여 연령에 맞는 콘텐츠를 제공합니다. `REQUIRED`는 사용자 연령 정보를 설정하도록 안내합니다. 브라질은 연령 정보 공유가 사용자·보호자의 선택에 기반하는 지역이므로, 사용자가 공유를 거부하면 Google Play는 `UNKNOWN`을 반환합니다. `UNKNOWN`을 받았을 때의 안내 방법은 `UNKNOWN` 상태 판별을 참조하세요.

Note

Hive SDK v4 26.7.0부터 Google Play는 브라질 사용자에게도 다른 지역과 동일한 상태값을 반환합니다. 기존에 브라질 대응 용도로 DECLARED 상태를 분기하던 코드가 있다면 DECLARED 상태 반환 중단과 대체를 참조하여 수정해야 합니다.

사전 준비: Age Range 모듈 추가¶

Age Range 모듈을 사용하기 위한 사전 준비 사항으로 각 SDK의 개발 엔진 및 타깃 OS에 따라 Age Range 모듈을 추가 혹은 제거합니다.

SDK Native Android¶

Age Range 모듈 추가¶

SDK 공통 설정의 market을 설정합니다.

모듈 수준의 build.gradle 파일에 아래 내용을 추가합니다.

implementation "com.com2us.android.hive:hive-agerange-google-agesignals"

Warning

Google Play Age Signals 라이브러리는 minSdkVersion 23 이상을 요구합니다. Hive SDK v4 본체는 21을 지원하지만, hive-agerange-google-agesignals 모듈을 추가하는 앱은 minSdkVersion을 23 이상으로 설정해야 합니다. 23 미만으로 설정하면 빌드 시 매니페스트 병합 단계에서 오류가 발생합니다.

Age Range 모듈 제거¶

모듈 수준의 build.gradle 파일에서 아래 내용을 제거합니다.

// implementation "com.com2us.android.hive:hive-agerange-google-agesignals" // 미사용 시 이 라인 제거

SDK Native iOS¶

Age Range 모듈 추가¶

앱스토어 책임법 관련 시스템 API는 iOS 26.2 이상에서만 지원됩니다.

Podfile 예제 코드를 참조하여 Age Range 모듈 설정 내용을 추가합니다.

target 'HIVE_GAME_COOL' do
  pod 'HiveAgeRangeApple', '${SDK_VERSION}'
  # 26.3.4 이후 '앱 내 중요한 변경 사항 알림 및 승인 요청' 선택 적용 가능
  pod 'HiveAgeRangePermissionApple', '${SDK_VERSION}'  # (26.3.4+ Optional)
end

SDK Native iOS 환경에서 아래 순서대로 Declared Age Range 권한을 추가합니다.
1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 프로젝트를 선택하세요.
2. TARGETS 목록에서 앱을 선택하세요.
3. Signing & Capabilities 탭을 클릭하세요.
4. Signing & Capabilities 탭 좌측 상단에 있는 + Capability 버튼을 클릭하세요.
5. 목록에서 Declared Age Range를 선택해 추가합니다.
6. Signing & Capabilities 목록에 추가된 Declared Age Range를 확인할 수 있습니다.

Age Range 모듈 제거¶

Podfile 예제 코드를 참조하여 Age Range 모듈 설정 내용을 제거합니다.

target 'HIVE_GAME_COOL' do
end

SDK Cocos2d-x Android¶

SDK Native Android와 동일합니다.

SDK Cocos2d-x iOS¶

SDK Native iOS와 동일합니다.

SDK Unity Android¶

Android 타깃 Unity 환경에서 Age Range 모듈을 사용하려면 아래의 순서대로 설정합니다.

Hive > ExternalDependency를 클릭합니다.
Market Settings 설정 아래 지원하는 스토어의 Age Range [Market] 항목을 체크합니다. Age Range 모듈은 지원하려는 스토어 모듈을 필요로 합니다.

※ Age Range 모듈을 사용하지 않으려면 체크를 해제합니다.
Age Range Google과 Age Range Apple 모듈을 사용하지 않으면 체크를 해제할 수 있습니다. Age Range Amazon 및 Age Range Samsung 모듈은 각 상위의 스토어 모듈을 포함하면 자동으로 포함됩니다.

Warning

Google Play Age Signals 라이브러리는 minSdkVersion 23 이상을 요구합니다. 자세한 내용은 SDK Native Android를 참조하세요.

SDK Unity iOS¶

앱스토어 책임법 관련 시스템 API는 iOS 26.2 이상에서만 지원됩니다.

Hive > ExternalDependency를 클릭합니다.
Market Settings 설정 아래 지원하는 스토어의 Age Range [Market] 항목을 체크합니다. Age Range 모듈은 지원하려는 스토어 모듈이 필요합니다.

※ Age Range 모듈을 사용하지 않으려면 체크를 해제합니다.
Age Range Apple과 Age Range Permission Apple 모듈을 사용하지 않으면 체크를 해제할 수 있습니다.

iOS 타깃 Unity 환경에서 Age Range 모듈을 사용하려면 아래 순서대로 Declared Age Range 권한을 추가합니다. Unity 에디터로 간편하게 설정할 수 있습니다.

Unity 상단에서 Hive를 선택합니다.
Build project post process setting > iOS를 선택합니다.
Hive PostProcess Editor(iOS)에서 Age Range 체크박스를 선택합니다.
iOS project export 이후 Signing & Capabilities 목록에 추가된 Declared Age Range를 확인할 수 있습니다.

SDK Unreal Engine Android¶

Android 타깃 Unreal Engine 환경에서 Age Range 모듈을 사용하려면 아래의 순서대로 설정합니다.

Unreal Editor > Edit > Project Settings를 선택합니다.
Project Settings 좌측 패널에서 Hive SDK > Dependency > Android를 선택합니다.
Hive Module > Enable AgeRange에 체크합니다.

※ AgeRange 모듈을 사용하지 않으려면 체크를 해제합니다.

Warning

Google Play Age Signals 라이브러리는 minSdkVersion 23 이상을 요구합니다. 자세한 내용은 SDK Native Android를 참조하세요.

SDK Unreal Engine iOS¶

앱스토어 책임법 관련 시스템 API는 iOS 26.2 이상에서만 지원됩니다.

iOS 타깃 Unreal Engine 환경에서 Age Range 모듈을 사용하려면 아래의 순서대로 설정합니다.

Unreal Editor > Edit > Project Settings를 선택합니다.
Project Settings 좌측 패널에서 Hive SDK > Dependency > iOS를 선택합니다.
Hive Module > Enable AgeRange에 체크합니다.

※ AgeRange 모듈을 사용하지 않으려면 체크를 해제합니다.
Declared Age Range 권한을 추가합니다.
Unreal Engine 5Unreal Engine 4
entitlements 파일에 아래 키를 추가하세요. entitlements 파일의 생성과 적용 방법은 Entitlements 설정 (iOS)을 참조하세요.
<key>com.apple.developer.declared-age-range</key> <true/>
IOSExport.cs의 entitlements 생성부에 아래 코드를 추가하세요. 수정 위치는 Entitlements 설정 (iOS)을 참조하세요.
// Add // Age Range 모듈 사용을 위해 필요한 항목입니다. Text.AppendLine("\t<key>com.apple.developer.declared-age-range</key>"); Text.AppendLine("\t<true/>"); // Add End

사용자 연령 범위 및 승인 상태 요청¶

사용자의 연령 및 보호자 승인 상태를 확인하기 위해 런타임 앱에서 getAgeRange API를 호출합니다. 해당 API는 앱 실행 시마다 반드시 호출해야 하는 필수 항목은 아니며, 서비스 정책 또는 기능 요구사항에 따라 필요 시 호출할 수 있습니다. 아래와 같은 경우에 호출을 고려할 수 있습니다.

앱 실행 시 사용자 연령 또는 보호자 승인 상태를 기반으로 기능 또는 콘텐츠를 제어해야 하는 경우
앱 업데이트로 인해 연령 등급에 영향을 줄 수 있는 변경 사항이 있는 경우
중대한 변경 등으로 보호자 재동의가 필요한 경우

앱에서 자체적인 연령 확인 기능을 제공하는 경우에도, Age Range API를 먼저 호출하여 스토어에서 제공하는 사용자 연령 정보를 우선 활용하는 것을 권장합니다.

Warning

Google Play는 getAgeRange 호출 중에 연령 정보 공유 동의 화면을 표시할 수 있습니다. 연령 정보 공유가 사용자·보호자의 선택에 기반하는 지역에서 아직 동의하지 않은 사용자가 호출한 경우가 이에 해당합니다.

동의 화면이 표시되는 시점을 앱에서 제어할 수 없으므로, 게임 플레이 중이 아닌 앱 실행 초기와 같이 화면 전환이 자연스러운 시점에 호출하세요. 한 세션에서 반복 호출하지 말고, 1회만 호출한 뒤 그 결과를 보관하여 사용하세요.

Google Play는 응답 대기에 제한 시간이 있습니다. 제한 시간을 초과하면 ResultAPI.TIMEOUT을 반환합니다.

getAgeRange API 호출¶

getAgeRange API를 호출하면 사용자 상태(userStatus)와 연령 범위(ageLower, ageUpper)를 반환합니다.

사용자 연령 범위를 요청하는 getAgeRange API 호출 예제 코드는 아래와 같습니다.

UnityC++KotlinJavaSwiftObjective-CUnreal Engine

API Reference: Unity®

using hive;

AuthV4.getAgeRange((ResultAPI result, AuthV4.AgeRange ageRange) => {
    if (!result.isSuccess() || ageRange == null) return;

    int status = ageRange.userStatus;
    int source = ageRange.ageRangeSource;   // 1~4, 정보 없으면 -1
});

API Reference: C++

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
using namespace std;
using namespace hive;

hive::AuthV4::getAgeRange([](hive::ResultAPI const& result, hive::AgeRange const& ageRange) {
    if (!result.isSuccess()) return;

    if (ageRange.ageRangeSource == hive::AgeRangeSource::TIER_A) {
        // 자가 신고로 확인된 연령
    }
});

API Reference: Kotlin

import com.hive.AuthV4;
import com.hive.ResultAPI;

AuthV4.getAgeRange(object : AuthV4.AuthV4GetAgeRangeListener {
    override fun onAuthV4GetAgeRange(result: ResultAPI, ageRange: AuthV4.AgeRange?) {
        if (!result.isSuccess || ageRange == null) return

        val userStatus = ageRange.userStatus                        // Int (AuthV4.UserStatus 의 value)
        val ageLower = ageRange.ageLower                            
        val ageUpper = ageRange.ageUpper                            
        val approvalDate = ageRange.mostRecentApprovalDate          
        val ageRangeId = ageRange.ageRangeId                        // Google: installId(UUID)
        val ageRangeSource = ageRange.ageRangeSource                // 1~4, -1 이면 값 없음

        // 열거형으로 비교하려면
        when (AuthV4.UserStatus.getUserStatus(userStatus)) {
            AuthV4.UserStatus.VERIFIED -> { /* 성인 */ }
            AuthV4.UserStatus.SUPERVISED -> { /* 미성년 */ }
            else -> { /* UNKNOWN, REQUIRED 등 */ }
        }
    }
})

API Reference: Java

import com.hive.AuthV4;
import com.hive.ResultAPI;

AuthV4.getAgeRange((result, ageRange) -> {
    if (!result.isSuccess() || ageRange == null) return;

    int userStatus = ageRange.getUserStatus();      
    int ageLower = ageRange.getAgeLower();
    int ageUpper = ageRange.getAgeUpper();
    String approvalDate = ageRange.getMostRecentApprovalDate();
    String ageRangeId = ageRange.getAgeRangeId();
    int ageRangeSource = ageRange.getAgeRangeSource();              // 1~4, -1 이면 값 없음

});

API Reference: Swift

import HIVEService    

AuthV4Interface.getAgeRange { result, ageRange in
    guard result.isSuccess, let ageRange = ageRange else { return }

    let status = ageRange.userStatus
    // ageRangeSource 는 Android 전용이며 iOS 응답에는 없습니다.
}

API Reference: Objective-C

#import <HIVEService/HIVEService-Swift.h>

[HIVEAuthV4 getAgeRange:^(HIVEResultAPI *result, HIVEAgeRange *ageRange) {
    if ([result isSuccess]) {
        // API call success    
    }    
}];

#include "HiveAuthV4.h"

FHiveAuthV4::GetAgeRange(FHiveAuthV4OnGetAgeRangeDelegate::CreateLambda(
    [](const FHiveResultAPI& Result, const FHiveAuthV4AgeRange& AgeRange) {
        if (!Result.isSuccess()) return;

        if (AgeRange.AgeRangeSource == EHiveAgeRangeSource::TIER_A) {
            // 자가 신고로 확인된 연령
        }
}));

getAgeRange API 호출 성공 시¶

getAgeRange 호출이 성공하면 userStatus와 ageLower, ageUpper를 이용하여 사용자 연령 및 승인 상태를 확인할 수 있습니다.

기본으로 제공하는 연령 범위는 아래와 같습니다.

0~12세
13~15세
16~17세
18세 이상

Google Play는 이 기본 구간을 그대로 사용하며, 필요한 경우에만 선택적으로 조정할 수 있습니다. 앱의 서비스 정책에 맞는 연령 구간이 따로 있다면 Google Play Console의 연령 신호에서 앱의 최소 연령을 최대 3개까지 입력하면 됩니다. 최소 연령 사이의 간격은 2세 이상이어야 하며 연 1회만 변경할 수 있습니다. 자세한 내용은 Google Play 공식 문서를 참조하세요.

Warning

연령 범위를 바꾸면 ageLower와 ageUpper로 돌아오는 값도 함께 달라집니다. 앱에서 특정 나이를 기준으로 분기한다면 Google Play Console에 설정한 구간과 맞는지 확인하세요.

Note

Apple App Store는 userStatus가 SUPERVISED인 상태에서 앱 내 중요한 변경 사항이 발생한 경우 showAgeRangeUpdatePermission API를 호출하여 보호자에게 변경 사항을 알리고 승인을 요청합니다.

userStatus	앱 처리
`UNKNOWN`	사용자 연령을 확인할 수 없는 상태입니다. 연령 확인 법규가 적용되지 않는 지역의 사용자가 대부분이지만, 그 외의 경우도 포함됩니다. Google Play에서는 `UNKNOWN`이 여러 원인을 포함하므로, 연령 확인 대상이 아니라고 단정하기 전에 `UNKNOWN` 상태 판별을 확인하세요.
`VERIFIED`	사용자 연령 범위(`ageLower`, `ageUpper`)를 확인하여 연령에 맞는 콘텐츠를 제공합니다.
`SUPERVISED`	사용자 연령 범위(`ageLower`, `ageUpper`)를 확인하여 연령에 맞는 콘텐츠를 제공합니다. Apple App Store로 배포하는 앱은 앱 내 중요한 변경 사항이 발생한 경우 `showAgeRangeUpdatePermission` API를 호출하여 보호자 승인을 요청합니다. Android에서는 이 API가 `NOT_SUPPORTED`를 반환하므로 각 스토어의 개발자 콘솔을 통해 알립니다. `SUPERVISED`는 추가 보호자 승인이 필요하지 않은 미성년자 상태입니다. 이미 승인을 받은 경우와, 앱이 승인을 요청하지 않아 승인이 필요하지 않은 경우가 모두 포함됩니다.
`SUPERVISED_APPROVAL_PENDING`	보호자 승인이 진행 중인 상태입니다. 사용자 연령 범위(`ageLower`, `ageUpper`)를 확인하여 연령에 맞는 콘텐츠를 제공하며, 앱 서비스 정책에 따라 기능 또는 콘텐츠를 제한할 수 있습니다.
`SUPERVISED_APPROVAL_DENIED`	보호자 승인이 거부된 상태입니다. 사용자 연령 범위(`ageLower`, `ageUpper`)를 확인하여 연령에 맞는 콘텐츠를 제공하며, 앱 서비스 정책에 따라 기능 또는 콘텐츠를 제한할 수 있습니다.
`REQUIRED`	사용자 연령 정보를 확인할 수 없는 상태입니다. 스토어 앱 또는 기기 설정에서 연령 정보를 설정하도록 안내합니다.
`DECLARED`	사용자 연령 범위(`ageLower`, `ageUpper`)를 확인하여 연령에 맞는 콘텐츠를 제공합니다. Hive SDK v4 26.7.0부터 Google Play는 이 상태를 반환하지 않습니다. DECLARED 상태 반환 중단과 대체를 참조하세요.

getAgeRange API 호출 실패 시¶

앱에서 getAgeRange API 요청 후 호출에 실패하면 아래와 같은 ResultAPI 실패 코드가 수신됩니다.

/*
 * RESPONSE_FAIL, NETWORK, DEVELOPER_ERROR, NOT_SUPPORTED
 * TIMEOUT, INVALID_PARAM (Google Play)
 */
ResultAPI.isSuccess() == false

Google Play에서 추가로 발생할 수 있는 실패 코드는 아래와 같습니다.

TIMEOUT: 제한 시간 내에 Google Play가 응답하지 않았습니다.
INVALID_PARAM: 연령 정보 공유 동의 화면을 표시할 Activity를 찾을 수 없습니다. AuthV4.setup 이후 앱이 화면에 있는 상태에서 호출해야 합니다.

API 호출 오류는 최신 버전이 아닌 스토어 앱을 사용하는 등의 다양한 이유로 발생할 수 있습니다.

사용자가 연령 정보 공유를 거부한 경우는 호출 실패가 아닙니다. 이때는 호출이 성공하고 userStatus가 UNKNOWN으로 반환되므로 UNKNOWN 상태 판별에 따라 처리하세요.

세션 진행 중에 오류가 발생한 경우, 최대 API 호출 재시도 횟수를 초과하면 호출을 종료하는 방식과 같이 최대한 사용자 환경을 방해하지 않도록 구현해야 합니다.

getAgeRange API 응답 데이터¶

getAgeRange API 응답 필드에 대한 설명은 아래와 같습니다. 각 필드 값을 활용하여 연령에 따른 앱 프로세스를 제공합니다.

응답 값은 변경될 수 있으며, 최신 값을 원하시면 앱이 열릴 때 API 응답을 요청하세요.

Response field	Values	Description
`userStatus`	VERIFIED	사용자가 만 18세 이상입니다.
	SUPERVISED	사용자에게 부모가 연령을 설정한 감독 대상 계정이 있습니다. `ageLower` 및 `ageUpper`를 사용하여 사용자의 연령대를 확인합니다. 추가 보호자 승인이 필요하지 않은 미성년자 상태입니다. 이미 승인을 받은 경우와, 앱이 승인을 요청하지 않아 승인이 필요하지 않은 경우가 모두 포함됩니다. 승인이 필요한 상태는 `SUPERVISED_APPROVAL_PENDING`과 `SUPERVISED_APPROVAL_DENIED`로 구분됩니다.
	SUPERVISED_APPROVAL_PENDING	사용자에게 감독 대상 계정이 있으며, 감독 부모가 아직 하나 이상의 대기 중인 중요한 변경 사항을 승인하지 않았습니다. `ageLower` 및 `ageUpper`를 사용하여 사용자의 연령대를 확인합니다. `mostRecentApprovalDate`를 사용하여 승인된 마지막 중요한 변경 사항을 확인합니다.
	SUPERVISED_APPROVAL_DENIED	사용자에게 관리 대상 계정이 있으며, 관리 대상 사용자의 부모가 하나 이상의 중요한 변경 사항에 대한 승인을 거부했습니다. `ageLower`, `ageUpper` 및 `mostRecentApprovalDate`를 사용하여 마지막으로 승인된 중요한 변경 사항을 확인하세요.
	UNKNOWN	사용자 연령을 확인할 수 없습니다. 해당 관할권 및 지역 외 사용자이거나, 만 18세 이상 혹은 미만일 수도 있습니다. Hive 콘솔 > 프로비저닝 > SDK 설정에서 사용자 연령 확인을 확인 안 함으로 설정하면 `UNKNOWN` 응답을 받습니다. Google Play는 Hive SDK v4 26.7.0부터 연령 정보 공유는 이루어졌으나 연령 범위를 받지 못한 경우, 보호자 승인 상태를 해석할 수 없는 경우에도 이 값을 반환합니다. 자세한 내용은 `UNKNOWN` 상태 판별을 참조하세요.
	REQUIRED	해당 관할권 및 지역에서 사용자가 확인 또는 감독되지 않았습니다. 이러한 사용자는 만 18세 이상일 수도 있고 미만일 수도 있습니다. 연령 확인을 받으려면 사용자에게 기기 설정 및 스토어 앱을 방문하여 상태를 확인하도록 요청하세요.
	DECLARED	사용자, 부모 또는 법적 보호자가 사용자의 연령을 신고했습니다. `ageLower`, `ageUpper`를 사용하여 사용자의 연령대를 확인합니다. Hive SDK v4 26.7.0부터 Google Play는 이 값을 반환하지 않습니다. 자가 신고 여부는 `ageRangeSource`로 확인합니다. Apple App Store는 이 값을 반환하지 않으며, Amazon Appstore와 Samsung Galaxy Store는 브라질 ECA를 지원하지 않아 브라질 관련 응답을 반환하지 않습니다.
`ageLower`	0 to 18	감독 대상 사용자의 연령 범위의 하한(포함)입니다. `ageLower` 및 `ageUpper`를 사용하여 사용자의 연령대를 확인합니다.
	-1	`userStatus`가 UNKNOWN, REQUIRED입니다. Google Play는 Hive SDK v4 26.7.0부터 `userStatus`가 UNKNOWN이어도 연령 범위와 `ageRangeId`를 반환하는 경우가 있습니다. `UNKNOWN` 상태 판별을 참조하세요.
`ageUpper`	2 to 18	감독 대상 사용자의 연령 범위의 상한(포함)입니다. `ageLower` 및 `ageUpper`를 사용하여 사용자의 연령대를 확인합니다.
	-1	사용자가 만 18세 이상이거나 `userStatus`가 UNKNOWN, REQUIRED입니다. Google Play는 Hive SDK v4 26.7.0부터 `userStatus`가 UNKNOWN이어도 연령 범위와 `ageRangeId`를 반환하는 경우가 있습니다. `UNKNOWN` 상태 판별을 참조하세요.
`mostRecentApprovalDate`	Datestamp	승인된 가장 최근의 중요한 변경 사항의 날짜입니다. 예: "2023-07-01T00:00:00.008Z" Apple App Store는 지원하지 않습니다. Samsung Galaxy Store는 YYYY-MM-DD 형태의 데이터를 반환합니다.
	Empty (a blank value)	`userStatus`가 SUPERVISED이며 제출된 큰 변화가 없습니다. 또는 `userStatus`가 UNKNOWN, REQUIRED입니다. Apple App Store는 지원하지 않습니다.
`ageRangeId`	App Store generated ID	스토어에서 생성된 식별자 ID입니다. Google Play: Google Play에서 감독 대상 사용자 설치에 할당한 ID로 `installID`입니다. 앱 승인 취소를 알리는 데 사용됩니다. 앱 승인 취소를 참조하세요. Amazon Appstore: Amazon 계정의 `userId`입니다. Apple App Store: 지원하지 않습니다. Samsung Galaxy Store: Samsung Galaxy Store에서 생성된 `ID`입니다.
	Empty (a blank value)	`userStatus`가 UNKNOWN, REQUIRED입니다. Apple App Store는 지원하지 않습니다. Google Play는 Hive SDK v4 26.7.0부터 `userStatus`가 UNKNOWN이어도 연령 범위와 `ageRangeId`를 반환하는 경우가 있습니다. `UNKNOWN` 상태 판별을 참조하세요.
`ageRangeSource`	1 (TIER_A)	사용자가 직접 신고한 연령입니다. Hive SDK v4 26.7.0부터 추가된 필드입니다. 의미 있는 값은 Google Play만 반환하며, 다른 스토어는 항상 -1입니다.
	2 (TIER_B)	부모 또는 보호자가 설정하고 관리하는 연령입니다.
	3 (TIER_C)	신용카드, 이메일 주소, 셀피 평가, 정부 발급 신분증 또는 세금 ID를 사용하여 평가한 연령입니다.
	4 (TIER_D)	정부 발급 ID와 셀피의 조합 또는 디지털 ID로 확인한 연령입니다.
	-1	연령 확인 출처 정보가 없습니다.

Hive SDK v4 26.7.0부터 Google Play는 Google Play Age Signals 라이브러리 0.0.4를 사용합니다. 아래 세 가지는 Google Play에만 해당하며, Amazon Appstore, Samsung Galaxy Store, Apple App Store의 동작은 변경되지 않았습니다.

AuthV4.AgeRange의 기존 5개 필드(userStatus, ageLower, ageUpper, mostRecentApprovalDate, ageRangeId)는 이름과 타입, 의미가 모두 그대로이며 ageRangeSource 필드가 추가되었습니다. 따라서 대부분의 앱은 코드 수정 없이 동작하지만, Google Play 응답을 해석할 때는 아래 세 가지를 확인해야 합니다.

DECLARED 상태 반환 중단과 대체¶

Google Play는 DECLARED 상태를 반환하지 않습니다. 상수 자체는 하위 호환을 위해 남아 있으므로 컴파일 오류는 발생하지 않습니다. 다만 DECLARED로 분기하던 코드는 아무 오류도 남기지 않은 채 그 분기만 더 이상 실행되지 않습니다.

사용자가 직접 신고한 연령인지 여부는 ageRangeSource로 확인합니다.

기존 (0.0.3)	대체 (0.0.4)
`userStatus == DECLARED`	`ageRangeSource == 1` (TIER_A)

Warning

ageRangeSource의 TIER_A는 DECLARED의 1:1 대체가 아닙니다.

DECLARED는 실질적으로 브라질 사용자를 구분하는 용도로 사용되었으나, ageRangeSource에는 국가 및 관할 지역 정보가 없습니다.
자가 신고는 지역과 무관하게 발생할 수 있으므로, 두 값을 기계적으로 치환하면 브라질 외 지역의 사용자까지 브라질 대응 로직으로 처리됩니다.
지역별로 다르게 대응해야 하는 경우 앱에서 Configuration.hiveCountry로 국가를 직접 확인해야 합니다. 이 값은 접속 IP를 기준으로 하므로 Google Play 계정에 설정된 국가와 다를 수 있습니다.

또한 자가 신고로 18세 이상이 확인된 사용자는 이제 VERIFIED로 반환됩니다. 0.0.3에서는 DECLARED로 구분되어 검증되지 않은 자가 신고임을 알 수 있었으나, 0.0.4에서는 ageRangeSource를 함께 확인해야 구분할 수 있습니다.

userStatus와 연령 확인 출처¶

userStatus는 사용자의 연령을 어떤 경로로 확인했는지를 구분하지 않습니다. 자가 신고(TIER_A)로 18세 이상이 확인된 사용자도 정부 발급 신분증으로 확인된 사용자와 동일하게 VERIFIED로 반환됩니다.

연령 확인 출처에 따라 다르게 처리해야 하는 경우 ageRangeSource를 함께 확인하세요. 이 필드는 정수 값이며, C++와 Unreal Engine에서는 각각 hive::AgeRangeSource와 EHiveAgeRangeSource 상수로 비교할 수 있습니다.

Warning

ageRangeSource는 연령 확인 출처를 구분하는 값이며, 숫자 크기가 우열을 뜻하지 않습니다. TIER_C에는 정부 발급 신분증이나 세금 ID로 평가한 경우가 포함되고, TIER_D는 정부 발급 신분증과 셀피 평가 등을 조합한 경우입니다.

특정 출처만 허용하려면 ageRangeSource >= 3처럼 크기로 비교하지 말고, 허용할 값을 직접 지정하여 확인하세요. 각 값의 의미는 Google Play 공식 문서에서도 확인할 수 있습니다.

UNKNOWN 상태 판별¶

UNKNOWN은 사용자 연령을 확인할 수 없는 상태입니다. 연령 확인 대상이 아니라는 뜻이 아니므로, UNKNOWN이라는 이유만으로 그대로 통과시키면 안 됩니다.

법안이 시행된 국가 중 미국은 사용자 연령을 알 수 없을 때 UNKNOWN이 아니라 REQUIRED를 반환합니다. 따라서 UNKNOWN을 받았을 때 추가로 판단해야 하는 대상은 브라질 사용자뿐입니다. Google Play의 응답에는 국가 정보가 없으므로, 브라질에 서비스하는 앱이라면 Configuration.hiveCountry로 국가를 직접 확인하세요.

Note

Apple App Store는 브라질 사용자의 연령 정보를 확인할 수 없는 경우 UNKNOWN이 아니라 REQUIRED를 반환합니다.

브라질 사용자로 확인되면 ageRangeSource 값에 따라 안내가 나뉩니다.

`ageRangeSource`	사용자 상태	앱 안내
-1이 아님	연령 정보 공유는 허용했으나 연령을 확인하지 못했습니다.	Google Play 앱에서 연령 인증을 진행하도록 안내합니다.
-1	연령 정보 공유를 허용하지 않았습니다.	연령 정보 공유를 허용하도록 안내합니다.

두 경우를 구분하지 않고 연령 확인이 필요합니다처럼 하나의 문구로 안내해도 됩니다. 브라질에서 UNKNOWN을 받은 사용자가 앱을 계속 이용하게 할지는 앱 서비스 정책에 따라 결정합니다.

사용자가 연령 정보 공유를 거부한 뒤 앱을 다시 실행하여 getAgeRange를 호출하면 Google Play가 공유 요청 화면을 다시 표시합니다. 이 화면을 몇 번까지 표시할지는 Google Play가 정하며, 사용자가 반복해서 닫거나 거부하면 더 이상 표시되지 않습니다.

UNKNOWN이어도 ageLower와 ageUpper에 값이 담겨 오는 경우가 있습니다. 이때는 연령이 확인된 18세 미만 사용자일 수 있으므로, 두 값을 확인하여 연령에 맞는 콘텐츠를 제공하세요.

Warning

조회에 실패한 경우에도 userStatus는 UNKNOWN으로 반환되며 응답 필드로는 구분되지 않습니다. UNKNOWN을 처리하기 전에 ResultAPI의 성공 여부를 먼저 확인하세요.

앱 내 중요한 변경 사항 알림 및 승인 요청¶

일부 관할권 및 지역의 규정에 따라 앱에 아래와 같은 변경 사항이 발생하는 경우, 앱에서는 보호자(부모)에게 변경 사항을 알리고, 미성년자인 사용자가 해당 앱을 계속 사용하도록 승인을 요청해야 합니다.

수집·저장·공유되는 데이터 변경
연령 등급 변경
새로운 인앱 구매나 광고 기능 추가
사용자 경험 변경 등

앱에서는 변경 사항을 언제 알리고 승인을 요청할지 결정합니다. 각 스토어별 변경 사항 알림 방법은 아래와 같습니다.

Google Play, Amazon Appstore, Samsung Galaxy Store: 각 스토어에서 운영하는 개발자 콘솔을 통한 알림
Apple App Store: 앱에서 직접 showAgeRangeUpdatePermission API를 호출하여 알림

showAgeRangeUpdatePermission API¶

Apple App Store로 배포하는 앱은 앱에서 직접 showAgeRangeUpdatePermission API를 호출하여 보호자(부모)에게 중요한 변경 사항을 알리고 승인을 요청합니다.

Warning

Android에서는 이 API가 동작하지 않으며 항상 ResultAPI.NOT_SUPPORTED를 반환합니다. Google Play, Amazon Appstore, Samsung Galaxy Store로 배포하는 앱은 각 스토어의 개발자 콘솔을 통해 변경 사항을 알려야 합니다.

Hive SDK 26.3.4부터 showAgeRangeUpdatePermission API를 사용하려면 HiveAgeRangePermissionApple 모듈을 추가해야 합니다. 자세한 내용은 SDK Native iOS를 참조하세요.

showAgeRangeUpdatePermission API를 호출하는 예제 코드는 아래와 같습니다.

UnityC++KotlinJavaSwiftObjective-CUnreal Engine

API Reference: Unity®

using hive;

String description = "This update adds video calling and location sharing features.";

AuthV4.showAgeRangeUpdatePermission(description, (ResultAPI result, AgeRange ageRange) => {    
    if (result.isSuccess()) {    
        // API call success    
    }    
});

API Reference: C++

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
using namespace std;
using namespace hive;

std::string description = "This update adds video calling and location sharing features.";

AuthV4::showAgeRangeUpdatePermission(description, [=](ResultAPI const & result, AgeRange const & ageRange) {
    if (result.isSuccess()) {    
        // API call success    
    }    
});

API Reference: Kotlin

import com.hive.AuthV4;
import com.hive.ResultAPI;

val description: String = "This update adds video calling and location sharing features."

AuthV4.showAgeRangeUpdatePermission(description, object : AuthV4.AuthV4GetAgeRangeListener {
    override fun onAuthV4GetAgeRange(result: ResultAPI, ageRange: AuthV4.AgeRange?) {
        if (result.isSuccess) {    
            // API call success
        } 
    }
})

API Reference: Java

import com.hive.AuthV4;
import com.hive.ResultAPI;

String description = "This update adds video calling and location sharing features.";

AuthV4.showAgeRangeUpdatePermission(description, (result, ageRange) -> {
    if (result.isSuccess()) {
        // API call success  
    }
});

API Reference: Swift

import HIVEService    

let description = "This update adds video calling and location sharing features."

AuthV4Interface.showAgeRangeUpdatePermission(description) { result, ageRange in    
    if result.isSuccess() {    
        // API call success    
    }    
}

API Reference: Objective-C

#import <HIVEService/HIVEService-Swift.h>

NSString *description = "This update adds video calling and location sharing features.";

[HIVEAuthV4 showAgeRangeUpdatePermission: description handler:^(HIVEResultAPI *result, HIVEAgeRange *ageRange) {
    if ([result isSuccess]) {
        // API call success    
    }    
}];

#include "HiveAuthV4.h"

FString Description = TEXT("This update adds video calling and location sharing features.");

FHiveAuthV4::ShowAgeRangeUpdatePermission(Description, FHiveAuthV4OnShowAgeRangeUpdatePermissionDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveAuthV4AgeRange& AgeRange) {
    if (Result.IsSuccess()) {
            // 호출 성공
    }
}));

보호자 승인 철회 알림¶

보호자(부모)는 앱 내 중요한 변경 사항 알림에 대한 승인을 했더라도 이후 승인을 취소할 수 있습니다. 승인을 취소하면 미성년자인 사용자는 더 이상 앱에 액세스할 수 없습니다.

보호자 승인 취소 시, 각 스토어를 통한 철회 알림 확인 방법은 아래와 같습니다.

Google Play: 연령 신호에서 installID 목록을 다운로드하면 철회 사실을 확인할 수 있습니다.
- Google Play의 installID는 3개월 동안 유효하며 이후 삭제됩니다.
Apple App Store: 승인 취소에 관한 알림을 보냅니다.
Amazon Appstore: 개발자 콘솔의 보고 섹션에서 Amazon userId를 다운로드하면 철회 사실을 알 수 있습니다.
Samsung Galaxy Store: 보호자 승인 철회 알림이 별도로 오지 않으므로 getAgeRange API를 호출하여 반환된 상태값으로 확인할 수 있습니다.

Age Range 테스트¶

Hive SDK에서는 연령 확인 법안 시행 유무에 상관없이 getAgeRange API 요청 시 정상 응답을 수신할 수 있는 테스트 환경과 테스트 케이스를 제공합니다.

Age Range 테스트 환경 및 테스트 케이스는 Android 타깃 개발 환경에서만 사용할 수 있으며, 디버그 모드 설정을 통해 API 동작을 시뮬레이션할 수 있습니다.

Note

iOS 타깃 개발 환경에서 Age Range 기능을 테스트하려면 Apple에서 제공하는 샌드박스 테스트 도구를 사용할 수 있습니다. Apple 샌드박스 계정으로 로그인해서 테스트하세요.

디버그 모드 사용 설정¶

Android 타깃 개발 환경에서 디버그 모드를 설정하려면 아래의 명령어를 실행합니다. 디버그 모드는 Hive ZoneType이 REAL이 아닌 경우(SANDBOX, TEST)에만 동작합니다.

명령어의 마지막 값에는 아래 테스트 케이스별 데이터 응답 절에 있는 TestCase 번호 1~19 중 하나를 넣습니다.

$ adb shell setprop debug.hive.agerange.testcase <TestCase 번호>

디버그 모드 설정은 앱에서 동작을 확인하기 위한 단위 테스트 또는 통합 테스트 용도로만 사용하세요.

테스트 케이스별 데이터 응답¶

Android 타깃 개발 환경에서 디버그 모드 설정 후 각 테스트 케이스별로 Google Play에서 반환하는 데이터 응답은 아래와 같습니다.

Warning

Hive SDK v4 26.7.0에서 테스트 케이스가 12개에서 19개로 늘어나고 번호가 재배치되었습니다. 26.6.0 이하에서 사용하던 테스트 케이스 번호는 26.7.0에서 다른 응답을 반환하므로, 기존 테스트 스크립트를 사용 중이라면 아래 표를 기준으로 번호를 다시 확인하세요.

TestCase	userStatus	ageLower	ageUpper	mostRecentApprovalDate	ageRangeId	ageRangeSource	Description
`1`	VERIFIED	18	-1	Empty	Empty	3 (TIER_C)	보호자 승인 대상이 아닌 18세 이상 사용자에 대한 응답입니다.
`2`	SUPERVISED	13	15	2026-01-01T07:00:00.008+0900	550e8400-e29b-41d4-a716-446655441111	2 (TIER_B)	보호자가 중요한 변경 사항을 승인한 13세부터 15세(포함) 사이의 사용자에 대한 응답입니다.
`3`	VERIFIED	18	-1	Empty	Empty	1 (TIER_A)	사용자가 직접 신고한 연령으로 18세 이상이 확인된 사용자에 대한 응답입니다.
`4`	SUPERVISED	13	15	2026-01-01T07:00:00.008+0900	550e8400-e29b-41d4-a716-446655441111	1 (TIER_A)	자가 신고 연령이며 보호자가 중요한 변경 사항을 승인한 사용자에 대한 응답입니다.
`5`	UNKNOWN	-1	-1	Empty	Empty	-1	연령 정보가 공유되지 않은 사용자에 대한 응답입니다. 연령 확인 법이 적용되지 않는 지역의 사용자와, 사용자 선택에 기반하는 지역에서 공유를 거부한 사용자가 모두 포함됩니다.
`6`	REQUIRED	-1	-1	Empty	Empty	-1	연령 확인 및 동의 여부를 확인할 수 없는 사용자에 대한 응답입니다.
`7`	SUPERVISED_APPROVAL_PENDING	0	12	Empty	550e8400-e29b-41d4-a716-446655441111	2 (TIER_B)	보호자 승인이 진행 중인 사용자에 대한 응답입니다.
`8`	SUPERVISED_APPROVAL_DENIED	0	12	2026-01-01T07:00:00.008+0900	550e8400-e29b-41d4-a716-446655441111	2 (TIER_B)	보호자가 승인을 거부한 사용자에 대한 응답입니다.
`9`	UNKNOWN	-1	-1	Empty	Empty	-1	연령 정보 공유 상태를 확인할 수 없는 경우의 응답입니다.
`10`	UNKNOWN	-1	-1	Empty	Empty	-1	연령 정보 공유 상태가 지정되지 않은 경우의 응답입니다.
`11`	VERIFIED	18	-1	Empty	Empty	4 (TIER_D)	보호자 승인 상태가 지정되지 않은 18세 이상 사용자에 대한 응답입니다.
`12`	UNKNOWN	-1	-1	Empty	Empty	-1	API가 ResultAPI.RESPONSE_FAIL 상태를 반환할 때의 응답입니다. (APP_NOT_OWNED)
`13`	UNKNOWN	-1	-1	Empty	Empty	-1	API가 ResultAPI.RESPONSE_FAIL 상태를 반환할 때의 응답입니다. (CLIENT_TRANSIENT_ERROR)
`14`	UNKNOWN	-1	-1	Empty	Empty	-1	API가 ResultAPI.RESPONSE_FAIL 상태를 반환할 때의 응답입니다. (INTERNAL_ERROR)
`15`	UNKNOWN	-1	-1	Empty	Empty	-1	API가 ResultAPI.RESPONSE_FAIL 상태를 반환할 때의 응답입니다. (API_NOT_AVAILABLE)
`16`	SUPERVISED	13	15	Empty	550e8400-e29b-41d4-a716-446655441111	1 (TIER_A)	보호자 승인 절차를 거치지 않고 연령만 확인된 13세부터 15세(포함) 사이의 사용자에 대한 응답입니다.
`17`	UNKNOWN	-1	-1	Empty	Empty	3 (TIER_C)	연령 정보는 공유되었으나 연령 범위를 확인할 수 없는 사용자에 대한 응답입니다. `ageRangeSource`가 -1이 아니라는 점으로 5, 9, 10번과 구분할 수 있습니다.
`18`	UNKNOWN	13	15	Empty	550e8400-e29b-41d4-a716-446655441111	2 (TIER_B)	보호자 승인 상태가 정의되지 않은 값으로 수신된 경우의 응답입니다. 연령이 확인된 18세 미만 사용자이므로 `ageLower`와 `ageUpper`를 확인해야 합니다.
`19`	SUPERVISED	0	12	Empty	550e8400-e29b-41d4-a716-446655441111	2 (TIER_B)	보호자 승인 절차를 거치지 않고 0세부터 12세(포함) 사이로 연령이 확인된 사용자에 대한 응답입니다.