앱스토어 책임법 대응

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

본 가이드에서는 Hive SDK에서 제공하는 Age Range 모듈의 동작 방식부터 사용 방법 및 테스트 방법을 설명합니다.

Age Range 동작 개요¶

Age Range 모듈에서 제공하는 기능은 아래와 같습니다.

• 사용자 연령 범위 및 승인 상태 확인
  • getAgeRange API
• 앱 내 중요한 변경사항 알림 및 승인 요청
  • showAgeRangeUpdatePermission API (Apple App Store만 지원)
  • 보호자 승인 철회 알림

마켓플레이스별 동작 플로우¶

마켓플레이스 별 Age Range 모듈의 동작 플로우는 아래와 같습니다.

• Google Play 및 Amazon Appstore

• Apple App Store

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

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

SDK Native Android¶

Age Range 모듈 추가¶

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

   // 앱스토어 책임법 대응 - Google
   implementation "com.com2us.android.hive:hive-agerange-google-agesignals"
   

Age Range 모듈 제거¶

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

// 앱스토어 책임법 대응 - Google
// implementation "com.com2us.android.hive:hive-agerange-google-agesignals" // 미 사용 시 이 라인 제거

SDK Native iOS¶

Age Range 모듈 추가¶

1. Podfile 예제 코드를 참고하여 앱스토어 책임법 관련 내용을 추가합니다.

   target 'HIVE_GAME_COOL' do
     pod 'HiveAgeRangeApple', '${SDK_VERSION}'
   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 예제 코드를 참고하여 앱스토어 책임법 관련 내용을 제거합니다.

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] 항목을 체크합니다. AgeRange 모듈은 지원하려는 마켓 모듈을 필요로 합니다.

※ AgeRange 모듈을 사용하지 않으려면 체크를 해제합니다.
AgeRange Google과 Apple AgeRange 모듈을 사용하지 않으면 체크를 해제할 수 있습니다. AgeRange Amazon 모듈은 Amazon AppStore 모듈을 포함하면 자동으로 포함됩니다.

SDK Unity iOS¶

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 타겟 Unreal Engine 환경에서 Age Range 모듈을 사용하려면 아래의 순서대로 설정합니다.

1. Unreal Editor → Edit → Project Settings를 선택합니다.
2. Project Settings 좌측 패널에서 Hive SDK → Dependency → iOS를 선택합니다.
3. Hive Module → Enable AgeRange에 체크합니다.
4. 앱에서 AgeRange 모듈을 사용하지 않으려면 체크를 해제합니다.

Unreal Engine 환경에서는 아래와 같은 entitlements template 을 통해 Declared Age Range 권한을 추가합니다. 사용 중인 entitlements template 파일에 키값을 추가하세요.

<key>com.apple.developer.declared-age-range</key>
<true/>

template을 사용 중이지 않다면, <앱_프로젝트_경로>/Plugins/HIVESDK/Source/HiveSDKiOS/template/HIVESDKV4Tester.entitlements 파일을 참고하세요.

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

사용자의 연령 및 보호자 승인 상태를 확인하기 위해 런타임 앱에서 getAgeRange API를 호출합니다. 본 컴플라이언스에 의한 법규 외에도 앱에서 별도의 연령 확인 절차가 있다면 getAgeRange API를 먼저 호출하여 연령을 확인하는 것이 좋습니다.

getAgeRange API를 호출하면 연령 확인 법규에 해당되는 지역에 거주하는 사용자의 상태 데이터 userState와 연령 범위가 응답으로 반환됩니다. 해당 관할 지역에 한해 반환되는 기본 연령 범위는 아래와 같으며 지역별 요건에 따라 변경될 수 있습니다.

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

getAgeRange API 호출¶

사용자 연령 범위를 요청하는 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 API 요청 후, 응답값인 userState에 따른 게임 앱 동작 플로우는 아래와 같습니다.

• UNKNOWN, VERIFIED, SUPERVISED 중 하나 : 앱을 진행하고 연령에 맞는 콘텐츠를 제공
  • SUPERVISED이면서 앱 내 중요한 변경 사항 알림 시 : Apple App Store로 배포한 게임에 한해 showAgeRangeUpdatePermission API 호출
• SUPERVISED_APPROVAL_PENDING 혹은 SUPERVISED_APPROVAL_DENIED :
  • 미성년자가 앱을 계속 사용하도록 동의하는 요청에 대한 보호자(부모) 승인이 아직 보류 중이거나 거부된 상태로, 연령을 확인하고 앱 진행 가능
• REQUIRED : 해당 관할권 및 지역에서 사용자 연령이 확인되지 않은 상태로, 마켓플레이스 앱이나 기기 설정에서 연령 정보를 공유하도록 안내하여 앱에서 연령을 확인할 수 있도록 유도

getAgeRange API 호출 실패 시¶

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

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

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

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

getAgeRange API 호출 응답 예시 (Apple App Store)¶

Apple App Store에서 getAgeRange API를 호출했을 때, 연령대 공유를 요청하는 팝업을 노출합니다.

연령대 공유를 선택한 유저만 연령대 및 승인 여부 확인이 가능하며, 거부한 경우 REQUIRED 상태가 수신됩니다.

getAgeRange API 응답 데이터¶

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

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

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

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

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

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

• Google Play 및 Amazon Appstore: 각 마켓플레이스에서 운영하는 개발자 콘솔을 통한 알림
• Apple App Store: 게임 앱에서 직접 showAgeRangeUpdatePermission API를 호출하여 알림

showAgeRangeUpdatePermission API¶

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

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 목록을 다운로드하면 철회 사실을 확인할 수 있습니다.
  • Goole Play의 installID는 3개월 동안 유효하며 이후 삭제됩니다.
• Apple App Store: 승인 취소에 관한 알림을 보냅니다.
• Amazon Appstore: 개발자 콘솔의 보고 섹션에서 Amazon userId를 다운로드하면 철회 사실을 알 수 있습니다.

Age Range 테스트¶

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

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

디버그 모드 사용 설정¶

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

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

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

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

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