Response to app store liability act

Hive SDK provides the Age Range module to verify user age in compliance with App Store Accountability Laws. As age verification bills that mandate user age verification are implemented, developers distributing apps through marketplaces can apply the Age Range module to verify user Age Ranges and request parental approval.

This guide explains the operation methods, usage, and testing methods of the Age Range module provided by Hive SDK.

Age Range operation overview¶

The features provided by the Age Range module are as follows:

• User Age Range and approval status verification
  • getAgeRange API
• In-app important change notifications and approval requests
  • showAgeRangeUpdatePermission API (Apple App Store only)
  • Parental approval revocation notifications

Operation flow by marketplace¶

The operation flow of the Age Range module by marketplace is as follows:

• Google Play 및 Amazon Appstore

• Apple App Store

[Preparation] Add Age Range module¶

As a preparation for using the Age Range module, add or remove the Age Range module according to each SDK's development engine and target OS.

SDK Native Android¶

Add Age Range module¶

1. Set the market in SDK common settings.
2. Add the following to the module-level build.gradle file:

   // App Store Accountability Law compliance - Google
   implementation "com.com2us.android.hive:hive-agerange-google-agesignals"
   

Remove Age Range module¶

Remove the following from the module-level build.gradle file:

// App Store Accountability Law compliance - Google
// implementation "com.com2us.android.hive:hive-agerange-google-agesignals" // Remove this line when not in use

SDK Native iOS¶

Add Age Range module¶

1. Refer to the Podfile example code and add App Store Accountability Law related content:

   target 'HIVE_GAME_COOL' do
     pod 'HiveAgeRangeApple', '${SDK_VERSION}'
   end
   

2. Add the Declared Age Range permission in the SDK Native iOS environment in the following order:

   1. Select your developer project in the project navigator of the Xcode project window.
   2. Select your developer app from the TARGETS list.
   3. Click the Signing & Capabilities tab.
   4. Click the + Capability button in the upper left corner of the Signing & Capabilities tab.
   5. Select Declared Age Range from the list to add it.
   6. You can verify the Declared Age Range added to the Signing & Capabilities list.

Remove Age Range module¶

Refer to the Podfile example code and remove App Store Accountability Law related content:

target 'HIVE_GAME_COOL' do
end

SDK Cocos2d-x Android¶

Same as SDK Native Android.

SDK Cocos2d-x iOS¶

Same as SDK Native iOS.

SDK Unity Android¶

To use the Age Range module in Android target Unity environment, configure it in the following order:

1. Click the Hive > ExternalDependency menu.
2. Check the Age Range [Market] item for the supported markets under Market Settings. The AgeRange module requires the market module you want to support.

※ Uncheck if you do not want to use the AgeRange module.
You can uncheck if you do not use AgeRange Google and Apple AgeRange modules. The AgeRange Amazon module is automatically included when you include the Amazon AppStore module.

SDK Unity iOS¶

To use the Age Range module in iOS target Unity environment, add the Declared Age Range permission in the following order. You can easily configure it with the Unity editor.

1. Select Hive from the Unity top menu.
2. Select Build project post process setting > iOS.
3. Select the Age Range checkbox in the Hive PostProcess Editor(iOS).
4. After iOS project export, you can verify the Declared Age Range added to the Signing & Capabilities list.

SDK Unreal Engine Android¶

To use the Age Range module in Android target Unreal Engine environment, configure it in the following order:

1. Select the Unreal Editor → Edit → Project Settings menu.
2. Select Hive SDK → Dependency → Android from the Project Settings left panel.

3. Check Hive Module → Enable AgeRange.

   ※ Uncheck if you do not want to use the AgeRange module.

SDK Unreal Engine iOS¶

To use the Age Range module in iOS target Unreal Engine environment, configure it in the following order:

1. Select Unreal Editor → Edit → Project Settings.
2. Select Hive SDK → Dependency → iOS from the Project Settings left panel.
3. Check Hive Module → Enable AgeRange.
4. Uncheck if you do not want to use the AgeRange module in the app.

In the Unreal Engine environment, add the Declared Age Range permission through the following entitlements template. Add the key value to the entitlements template file you are using:

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

If you are not using a template, refer to the /Plugins/HIVESDK/Source/HiveSDKiOS/template/HIVESDKV4Tester.entitlements file.

Request user Age Range and approval status¶

Call the getAgeRange API in the runtime app to verify the user's age and parental approval status. In addition to the laws governed by this compliance, if the app has a separate age verification process, it is recommended to call the getAgeRange API first to verify age.

When you call the getAgeRange API, the status data userState and Age Range of users residing in regions subject to age verification laws are returned as a response. The default Age Ranges returned for the applicable jurisdictions are as follows and may change according to regional requirements:

• 0~12 years old
• 13~15 years old
• 16~17 years old
• 18 years old and above

Call getAgeRange API¶

The example code for calling the getAgeRange API to request user Age Range is as follows:

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()) {
            // 호출 성공
    }
}));

When getAgeRange API call is successful¶

After requesting the getAgeRange API in the game app, the game app operation flow according to the response value userState is as follows:

• One of UNKNOWN, VERIFIED, SUPERVISED : Proceed with the app and provide age-appropriate content
  • When SUPERVISED and notifying important changes within the app : Call showAgeRangeUpdatePermission API only for games distributed to Apple App Store
• SUPERVISED_APPROVAL_PENDING or SUPERVISED_APPROVAL_DENIED :
  • Parental approval for the request for minors to continue using the app is still pending or has been denied. Age can be verified and app can proceed
• REQUIRED : User age has not been verified in the applicable jurisdiction and region. Guide users to share age information in marketplace apps or device settings to allow age verification in the app

When getAgeRange API call fails¶

After requesting the getAgeRange API in the game app, if the call fails, the following ResultAPI failure codes are received:

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

API call errors can occur for various reasons, such as using a marketplace app that is not the latest version.

If an error occurs during session progress, it should be implemented to minimize disruption to the user experience, such as terminating the call when the maximum number of API call retries is exceeded.

getAgeRange API call response example (Apple App Store)¶

When calling the getAgeRange API on Apple App Store, it displays a popup requesting Age Range sharing.

Only users who choose to share their Age Range can verify their Age Range and approval status, and if they decline, the REQUIRED status is received.

getAgeRange API response data¶

The description of the getAgeRange API response fields is as follows. You can use each field value to provide age-appropriate game processes.

Response values may change. If you want the latest values, request the API response when the app opens.

In-app important changes notification and approval request¶

According to regulations in some jurisdictions and regions, when the following changes occur in game apps, the game app side must notify parents of the changes and request approval for minor users to continue using the app:

• Changes to data collected, stored, or shared
• Age rating changes
• Addition of new in-app purchases or advertising features
• User experience changes, etc.

The game app side can decide when to notify changes and request approval. The method for notifying changes by each marketplace is as follows:

• Google Play and Amazon Appstore: Notification through developer consoles operated by each marketplace
• Apple App Store: Direct notification by calling the showAgeRangeUpdatePermission API in the game app

showAgeRangeUpdatePermission API¶

For apps distributed to the Apple App Store market, call the showAgeRangeUpdatePermission API directly in the app to notify parents of important changes and request approval.

The example code for calling the showAgeRangeUpdatePermission API is as follows:

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()) {
            // 호출 성공
    }
}));

Parental approval revocation notification¶

Parents can revoke approval for in-app important change notifications even after giving approval. When approval is revoked, minor users can no longer access the app.

When parental approval is revoked, the methods to check revocation notifications through each marketplace are as follows:

• Google Play: Download the installID list from the Age Signals page to confirm revocation.
  • Google Play's installID is valid for 3 months and is then deleted.
• Apple App Store: Sends notifications about approval revocation.
• Amazon Appstore: Download Amazon userId from the reporting section of the developer console to learn about revocation.

Age Range testing¶

Hive SDK provides a test environment and test cases that can receive normal responses when requesting the getAgeRange API regardless of whether the age verification law is implemented.

The Age Range test environment and test cases are only available in Android target development environments, and API operations can be simulated through debug mode settings.

Debug mode usage settings¶

To set debug mode in Android target development environments, run the following command. Debug mode operates in Hive ZoneType.SANDBOX.

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

Debug mode settings should be used only for unit testing or integration testing purposes to verify operation in game apps.

Data response by test case¶

After setting debug mode in Android target development environments, the data response returned by Google Play Store for each test case is as follows: