Minor protection legislation compliance

Hive SDK provides an Age range module that helps developers comply with app store accountability laws for protecting minors and Brazil's ECA by verifying user age. As age-verification regulations are rolled out, developers distributing apps through marketplaces can apply the Age range module to check user age ranges and request guardian approval.

To check a user's age range on iOS, the following requirements must be met.

• Xcode 26.2 or later
• Feature support on iOS 26.2 or later

This guide explains how the Age range module works in Hive SDK, how to use it, and how to test it.

Age range overview¶

The Age range module provides the following features.

• Check user age range and approval status
  • getAgeRange API
• Notify users about major in-app changes and request approval
  • showAgeRangeUpdatePermission API (Apple App Store only)
  • Guardian approval revocation notifications

Marketplace flow by store¶

The Age range module flow by marketplace is as follows.

• Google Play

• Amazon Appstore, Samsung Galaxy Store

• Apple App Store

Prerequisites: add the Age range module¶

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

SDK native Android¶

Add the Age range module¶

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

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

Remove the Age range module¶

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

// implementation "com.com2us.android.hive:hive-agerange-google-agesignals" // Remove this line when not used

SDK native iOS¶

Add the Age range module¶

For iOS, app-store-accountability-related system APIs are supported only on iOS 26.2 or later.

1. Refer to the Podfile example code and add the Age range module configuration.

   target 'HIVE_GAME_COOL' do
     pod 'HiveAgeRangeApple', '${SDK_VERSION}'
     # From 26.3.4, optional support for "notify major in-app changes and request approval"
     pod 'HiveAgeRangePermissionApple', '${SDK_VERSION}'  # (26.3.4+ Optional)
   end
   

2. In SDK native iOS, add the Declared Age Range capability in the following order.

   1. In Xcode Project navigator, select your developer project.
   2. In TARGETS, select your app target.
   3. Click the Signing & Capabilities tab.
   4. Click + Capability at the top left of Signing & Capabilities.
   5. Select and add Declared Age Range from the list.
   6. Verify Declared Age Range was added to Signing & Capabilities.

Remove the Age range module¶

Refer to the Podfile example code and remove the Age range module configuration.

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 Unity for Android targets, configure as follows.

1. Click the Hive > ExternalDependency menu.
2. Under Market Settings, check the Age Range [Market] items for supported markets. The Age range module depends on the selected market modules.

※ Uncheck to disable the Age range module.
You can uncheck Age Range Google and Age Range Apple when they are not used. Age Range Amazon and Age Range Samsung are included automatically when their parent market modules are included.

SDK Unity iOS¶

App-store-accountability-related system APIs are supported only on iOS 26.2 or later.

1. Click the [Hive > ExternalDependency] menu.
2. Under Market Settings, check Age Range [Market] for supported markets. The Age range module depends on the selected market modules.

※ Uncheck to disable the Age range module.
You can uncheck Age Range Apple and Age Range Permission Apple when they are not used.

To use the Age range module in Unity for iOS targets, add the Declared Age Range capability as follows. You can configure it easily from the Unity editor.

1. In the Unity top menu, select Hive.
2. Select Build project post process setting > iOS.
3. In Hive PostProcess Editor (iOS), check Age Range.
4. After iOS project export, verify Declared Age Range is added in Signing & Capabilities.

SDK Unreal Engine Android¶

To use the Age range module in Unreal Engine for Android targets, configure as follows.

1. In Unreal Editor, select Edit → Project Settings.
2. In the left panel, select Hive SDK → Dependency → Android.

3. Check Hive Module → Enable AgeRange.

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

SDK Unreal Engine iOS¶

For iOS, app-store-accountability-related system APIs are supported only on iOS 26.2 or later. To use the Age range module in Unreal Engine for iOS targets, configure as follows.

1. In Unreal Editor, select Edit → Project Settings.
2. In the left panel, select Hive SDK → Dependency → iOS.

3. Check Hive Module → Enable AgeRange.

   ※ Uncheck to disable the AgeRange module.

4. In Unreal Engine, add the Declared Age Range capability by editing IOSExport.cs.
   In Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExport.cs, 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
   // Required when using the Age range module.
   Text.AppendLine("\t<key>com.apple.developer.declared-age-range</key>");
   Text.AppendLine("\t<true/>");
   // Add End
   
   if (bCloudKitSupported) {
           if (iCloudContainerIdentifiersXML != "")
   

Edit the entitlements template (Unreal Engine 5)¶

In Unreal Engine 5 projects, add the Declared Age Range capability using an .entitlements_ template like below. Add the key to your existing _.entitlements template.

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

If you do not have an entitlements template, refer to HIVESDKV4Tester.entitlements under Plugins/HIVESDK/Source/HiveSDKiOS/template/.

Request user age range and approval status¶

Call the getAgeRange API at runtime to check the user's age and guardian approval status. This API is not mandatory on every app launch. Call it as needed based on your service policy or feature requirements. Typical cases for calling it include the following.

• You need to control features or content based on user age or guardian approval status at app launch.
• App updates include changes that may affect age ratings.
• Re-consent from guardians is required (for example, after major changes).

If your app has its own age-verification flow in addition to legal compliance requirements, we recommend calling getAgeRange first to verify age.

When getAgeRange is called, the response includes the user status data userState and age range for users living in regions where age-verification laws apply. The default age ranges returned for those jurisdictions are as follows and may change by regional requirements.

• 0 to 12
• 13 to 15
• 16 to 17
• 18+

Call the getAgeRange API¶

The following examples show how to call getAgeRange.

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()) {
            // Call succeeded
    }
}));

On successful getAgeRange calls¶

After calling getAgeRange, your game app can behave as follows based on userState.

• One of UNKNOWN, VERIFIED, or SUPERVISED: Continue app flow and provide age-appropriate content
  • If SUPERVISED and major in-app change notification is required: Call showAgeRangeUpdatePermission for games distributed via Apple App Store
• SUPERVISED_APPROVAL_PENDING or SUPERVISED_APPROVAL_DENIED:
  • Guardian approval for allowing the minor to continue using the app is pending or denied. Verify age and handle app progression according to your policy.
• REQUIRED: User age is not verified in the relevant jurisdiction/region. Prompt users to share age information via device settings or marketplace app settings.
• DECLARED: In Brazil, the user, parent, or legal guardian has declared the user's age. Provide age-appropriate content.

On failed getAgeRange calls¶

If a getAgeRange call fails, you may receive the following ResultAPI failure codes.

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

API errors can occur for many reasons, such as outdated marketplace apps.

If errors occur during a session, implement handling that minimizes user disruption, such as stopping retries after a maximum retry count.

Example getAgeRange response (Apple App Store)¶

When getAgeRange is called on Apple App Store, a popup asking for age-range sharing is displayed.

Only users who allow age-range sharing can return age/approval status. If the user denies it, REQUIRED is returned.

getAgeRange response data¶

The following describes getAgeRange response fields. You can use these fields to drive age-based game processes.

Response values can change. To get the latest values, request API responses when the app opens.

Notify major in-app changes and request approval¶

Under regulations in some jurisdictions/regions, if the game app has changes like the following, the app must notify guardians (parents) and request approval for minors to continue using the app.

• Changes to collected, stored, or shared data
• Changes to age rating
• Added in-app purchases or advertising features
• Changes to user experience

The game app can decide when to notify and request approval. Marketplace-specific methods are as follows.

• Google Play, Amazon Appstore, Samsung Galaxy Store: Notify through each marketplace's developer console
• Apple App Store: Notify directly from the game app by calling showAgeRangeUpdatePermission

showAgeRangeUpdatePermission API¶

For apps distributed through Apple App Store, call showAgeRangeUpdatePermission in your app to notify guardians (parents) of major changes and request approval.

From Hive SDK 26.3.4, using showAgeRangeUpdatePermission requires adding the HiveAgeRangePermissionApple module. See SDK native iOS for details.

The following examples show how to call showAgeRangeUpdatePermission.

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()) {
            // Call succeeded
    }
}));

Guardian approval revocation notification¶

Guardians (parents) can revoke approval even after approving major in-app change notifications. If approval is revoked, minors can no longer access the app.

You can check revocation by marketplace as follows.

• Google Play: Download the installID list from the Age signals page to identify revocations.
  • Google Play installID is valid for 3 months and then removed.
• Apple App Store: Sends approval revocation notifications.
• Amazon Appstore: Download Amazon userId data from the Reports section in the developer console.
• Samsung Galaxy Store: No separate revocation notification is sent, so call getAgeRange and check the returned status.

Age range testing¶

Hive SDK provides test environments and test cases so you can receive normal responses for getAgeRange regardless of whether age-verification laws are currently in effect.

The Age range test environment and test cases are available only for Android target development environments. You can simulate API behavior through debug mode.

Enable debug mode¶

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

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

Use debug mode only for unit or integration testing to verify behavior in game apps.

Responses by test case¶

After enabling debug mode in Android target development environments, Google Play Store returns the following data for each test case.