应用商店责任法回应

Hive SDK 提供 年龄范围 模块，用于验证用户年龄以符合应用商店问责法。随着强制用户年龄验证的年龄验证法案的实施，通过应用市场发布应用的开发者可以应用 年龄范围 模块来验证用户年龄范围并请求家长批准。

本指南说明了 Hive SDK 提供的 年龄范围 模块的操作方法、使用方法和测试方法。

年龄范围操作概览¶

年龄范围模块提供的功能如下：

• 用户年龄范围和批准状态验证
  • getAgeRange API
• 应用内重要变更通知和批准请求
  • showAgeRangeUpdatePermission API（仅限 Apple App Store）
  • 家长批准撤销通知

按应用市场的操作流程¶

按应用市场的年龄范围模块操作流程如下：

• Google Play、Amazon Appstore、Samsung Galaxy Store

  

• Apple App Store

[准备] 添加年龄范围模块¶

作为使用年龄范围模块的准备，根据各 SDK 的开发引擎和目标操作系统添加或移除年龄范围模块。

SDK Native Android¶

添加年龄范围模块¶

1. 在 SDK 通用设置 中设置市场。
2. 将以下内容添加到模块级别的 build.gradle 文件：

   // 应用商店问责法合规 - Google
   implementation "com.com2us.android.hive:hive-agerange-google-agesignals"
   

移除年龄范围模块¶

从模块级别的 build.gradle 文件中移除以下内容：

// 应用商店问责法合规 - Google
// implementation "com.com2us.android.hive:hive-agerange-google-agesignals" // 不使用时移除此行

SDK Native iOS¶

添加年龄范围模块¶

1. 参考 Podfile 示例代码 并添加应用商店问责法相关内容：

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

2. 在 SDK Native iOS 环境中按以下顺序添加声明的年龄范围权限：

   1. 在 Xcode 项目窗口的项目导航器中选择您的开发者项目。
   2. 从 TARGETS 列表中选择您的开发者应用。
   3. 单击"签名和功能"选项卡。
   4. 在"签名和功能"选项卡的左上角单击 + Capability 按钮。
   5. 从列表中选择 Declared Age Range 以添加它。
   6. 您可以验证已添加到"签名和功能"列表中的 Declared 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 环境中使用年龄范围模块，请按以下顺序配置：

1. 单击 Hive > ExternalDependency 菜单。

2. 在市场设置下，检查支持的市场的年龄范围 [Market] 项。年龄范围模块需要您要支持的市场模块。

   ※ 如果不想使用年龄范围模块，取消选中。
   如果不使用年龄范围 Google 和 Apple 年龄范围模块，可以取消选中。年龄范围 Amazon 和 年龄范围 Samsung 模块在您包含各自上层市场模块时会自动包含。

SDK Unity iOS¶

要在 iOS 目标 Unity 环境中使用年龄范围模块，请按以下顺序添加声明的年龄范围权限。您可以使用 Unity 编辑器轻松配置它。

1. 从 Unity 顶部菜单中选择 Hive。
2. 选择 Build project post process setting > iOS。
3. 在 Hive PostProcess Editor(iOS) 中选中 Age Range 复选框。
4. iOS 项目导出**后，您可以验证已添加到 **Signing & Capabilities 列表中的 Declared Age Range。

SDK Unreal Engine Android¶

要在 Android 目标 Unreal Engine 环境中使用年龄范围模块，请按以下顺序配置：

1. 选择 Unreal Editor → Edit → Project Settings 菜单。
2. 从 Project Settings 左侧面板中选择 Hive SDK → Dependency → Android。

3. 检查 Hive Module → Enable AgeRange。

   ※ 如果不想使用年龄范围模块，取消选中。

SDK Unreal Engine iOS¶

要在 iOS 目标 Unreal Engine 环境中使用年龄范围模块，请按以下顺序配置：

1. 选择 Unreal Editor → Edit → Project Settings。
2. 从 Project Settings 左侧面板中选择 Hive SDK → Dependency → iOS。

3. 检查 Hive Module → Enable AgeRange。

   ※ 如果不想使用年龄范围模块，取消选中。

4. 在 Unreal Engine 环境中，修改 IOSExport.cs 文件以添加声明的年龄范围权限。
   在 Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExport.cs 文件中，在 'Add' 和 '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 != "")
   

修改 entitlements 模板 (Unreal Engine 5)¶

在您的 Unreal Engine 5 项目中，使用 .entitlements_ 模板添加声明的年龄范围权限，如下所示。将键值对添加到您现有的 _.entitlements 模板中。

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

如果没有 entitlements 模板，可以参考 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()) {
                        // API call success
        }
}));

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、Samsung Galaxy Store：通过各应用市场运营的开发者控制台通知
• 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()) {
        // 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.
• Samsung Galaxy Store：由于不会单独收到撤销监护人同意的通知，因此可以调用 getAgeRagne API，通过返回的状态值进行确认。

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: