미성년자 보호 법안 대응

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

Age Range 동작 개요¶

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

사용 시점¶

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

iOS 요구 사항¶

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

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

Age Range 처리 흐름¶

OS별 구현 플로우¶

• Android

  • Google Play, Amazon Appstore, Samsung Galaxy Store

• iOS

  • Apple App Store

국가별 처리 예시¶

[사전 준비] Age Range 모듈 추가¶

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

SDK Native Android¶

Age Range 모듈 추가¶

1. SDK 공통 설정의 market을 설정합니다.
2. 모듈 수준의 build.gradle 파일에 다음을 추가합니다.

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

Age Range 모듈 제거¶

모듈 수준의 build.gradle 파일에서 다음을 제거합니다.

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

SDK Native iOS¶

Age Range 모듈 추가¶

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

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

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

2. 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 모듈을 사용하려면 아래의 순서대로 설정합니다.

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

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

SDK Unity iOS¶

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

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

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

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

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

SDK Unreal Engine Android¶

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

1. Unreal Editor → Edit → Project Settings 메뉴를 선택합니다.
2. Project Settings 좌측 패널에서 Hive SDK → Dependency → Android를 선택합니다.

3. Hive Module → Enable AgeRange에 체크합니다.

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

SDK Unreal Engine iOS¶

iOS의 경우, 앱스토어 책임법 관련 시스템 API는 iOS 26.2 이상에서만 지원됩니다. iOS 타깃 Unreal Engine 환경에서 Age Range 모듈을 사용하려면 아래의 순서대로 설정합니다.

1. Unreal Editor → Edit → Project Settings를 선택합니다.
2. Project Settings 좌측 패널에서 Hive SDK → Dependency → iOS를 선택합니다.

3. Hive Module → Enable AgeRange에 체크합니다.

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

4. 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를 먼저 호출하여 스토어에서 제공하는 사용자 연령 정보를 우선 활용하는 것을 권장합니다.

getAgeRange API 호출¶

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

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

using hive;

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

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

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

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

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

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

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

import HIVEService    

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

#import <HIVEService/HIVEService-Swift.h>

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

#include "HiveAuthV4.h"

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

getAgeRange API 호출 성공 시¶

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

연령 확인 법규가 적용되는 지역에서는 기본적으로 다음 연령 범위를 제공합니다. (지역별 정책에 따라 변경될 수 있습니다.)

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

getAgeRange API 호출 실패 시¶

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

/*
 * RESPONSE_FAIL, NETWORK, DEVELOPER_ERROR, NOT_SUPPORTED
 */
ResultAPI.isSuccess() == false

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

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

getAgeRange API 응답 데이터¶

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

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

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

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

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

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

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

showAgeRangeUpdatePermission API¶

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

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

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

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    
    }    
});

#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    
    }    
});

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
        } 
    }
})

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

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

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

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    
    }    
}

#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 동작을 시뮬레이션할 수 있습니다.

디버그 모드 사용 설정¶

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

$ adb shell setprop debug.hive.agerange.testcase 1~12

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

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

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