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.

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

4. In the Unreal Engine environment, modify the IOSExport.cs file to add the Declared Age Range permission.
   In the Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExport.cs file, add the lines between 'Add' and 'Add End'.

   Unreal Engine

   Text.AppendLine( "<dict>");
   Text.AppendLine( "\t<key>get-task-allow</key>");
   Text.AppendLine(string.Format( "\t<{0}/>", bForDistribution ? "false": "true"));
   
   // Add
   // Age Range 모듈 사용을 위해 필요한 항목입니다.
   Text.AppendLine("\t<key>com.apple.developer.declared-age-range</key>");
   Text.AppendLine("\t<true/>");
   // Add End
   
       if (bCloudKitSupported) {
               if (iCloudContainerIdentifiersXML != "")
   

Modify entitlements template (Unreal Engine 5)¶

In your Unreal Engine 5 project, add the Declared Age Range permission using the .entitlements_ template as shown below. Add the key-value to your existing _.entitlements template.

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

entitlements 템플릿이 없다면, Plugins/HIVESDK/Source/HiveSDKiOS/template/ 경로 하위의 HIVESDKV4Tester.entitlements 파일을 참고할 수 있습니다.

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 following is an example code for calling the getAgeRange API to request the user's age range.

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()) {
                        // API call success
        }
}));

On successful getAgeRange API call¶

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, or SUPERVISED : Proceed with the app and provide age-appropriate content * When notifying important in-app changes while SUPERVISED : Call the showAgeRangeUpdatePermission API only for games distributed on Apple App Store
• SUPERVISED_APPROVAL_PENDING or SUPERVISED_APPROVAL_DENIED : * The parental approval for the request for a minor to continue using the app is still pending or has been denied. Verify the age and allow the app to proceed.
• REQUIRED : The user's age has not been verified in the applicable jurisdiction and region. Guide users to share age information in the marketplace app or device settings so that the app can verify age.

On failed getAgeRange API call¶

After requesting the getAgeRange API in the game app, if the call fails, you will receive the following ResultAPI failure code:

/*
 * 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 a session, implement it to minimize disruption to the user's environment, such as ending the call if the maximum number of API call retries is exceeded.

Sample getAgeRange API call response (Apple App Store)¶

When calling the getAgeRange API on Apple App Store, a popup requesting age range sharing is displayed.

Only users who choose to share their age range can verify the age range and approval status. If denied, a REQUIRED status is received.

GetAgeRange API response data¶

The description of the getAgeRange API response fields is as follows. You can provide game processes based on age by utilizing each field value.

Response values may change. To get the latest values, request an API response when the app opens.

In-app important change notifications and approval requests¶

According to regulations in certain jurisdictions and regions, when the following changes occur in a game app, the game app must notify the parent or guardian of the change and request approval for a minor to continue using the app.

• Changes to data being collected, stored, or shared
• Changes to age rating
• Addition of new in-app purchases or advertising features
• Changes to user experience, etc.

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

• Google Play and Amazon Appstore: Notification through the developer console operated by each marketplace
• Apple App Store: Notification by directly calling the showAgeRangeUpdatePermission API from the game app

ShowAgeRangeUpdatePermission API¶

For apps distributed on Apple App Store, directly call the showAgeRangeUpdatePermission API from the app to notify the parent or guardian of important changes and request approval.

The following is an example code for calling the 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()) {
        // API call success
    }
}));

Parental approval revocation notification¶

Even after a parent or guardian has approved an important change notification in the app, they can cancel the approval later. If approval is revoked, a minor user will no longer have access to the app.

When a parent or guardian revokes approval, the method to check the revocation notification through each marketplace is as follows:

• Google Play: You can confirm the revocation by downloading the installID list from the Age Signals page. * Google Play's installID is valid for 3 months and will be deleted thereafter.
• Apple App Store: Sends a notification about approval revocation.
• Amazon Appstore: You can confirm the revocation by downloading the Amazon userId from the reports section in the developer console.

Age range testing¶

Hive SDK provides a test environment and test cases that allow you to receive normal responses when requesting the getAgeRange API, regardless of whether age verification bill has been implemented.

The Age Range test environment and test cases are only available in the Android target development environment, and you can simulate API behavior through debug mode settings.

Enable debug mode¶

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

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

Use debug mode settings only for unit testing or integration testing to verify behavior in a game app.

Data response by test case¶

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