Appstore

Hive SDK 提供了 年龄范围 模块，以验证用户年龄，以符合应用商店责任法。当实施要求用户年龄验证的年龄验证法案时，通过市场分发应用程序的开发者可以应用 年龄范围 模块来验证用户的年龄范围并请求父母的批准。

Note

**年龄范围**模块在Hive SDK v4 26.0.1版本中可用于Android和iOS目标，直到实施年龄验证法之前，不需要强制应用。

Warning

在年龄验证法实施之前，在接收实际用户状态和年龄信息的用户环境中添加年龄范围模块并调用getAgeRange API将导致各个市场（Google Play，Apple App Store）的错误响应。因此，在年龄验证法实施之前，不添加年龄范围模块是可以的，即使添加并调用它，也可以忽略除PENDING或DENIED等明确的行为错误响应以外的错误。
在法律实施之前，要接收正常响应，可以使用Apple提供的沙盒测试API和工具。有关更多详细信息，请参阅Apple的官方公告。

在年龄验证法实施后，添加年龄范围模块并调用getAgeRange API将允许您实时接收用户状态和年龄信息。（将提供单独通知）

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

年龄范围操作概述¶

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

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

按市场划分的操作流程¶

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

Google Play 和 Amazon Appstore
苹果应用商店

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

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

SDK 原生 Android¶

添加年龄范围模块¶

在SDK公共设置中设置市场。

将以下内容添加到模块级别的 build.gradle 文件中：

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

移除年龄范围模块¶

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

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

SDK 原生 iOS¶

添加年龄范围模块¶

请参考Podfile示例代码，并添加与App Store责任法相关的内容：

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

在SDK原生iOS环境中按以下顺序添加声明的年龄范围权限：
1. 在Xcode项目窗口的项目导航器中选择您的开发者项目。
2. 从TARGETS列表中选择您的开发者应用。
3. 点击“签名与能力”选项卡。
4. 点击“签名与能力”选项卡左上角的**+ 能力**按钮。
5. 从列表中选择**声明的年龄范围**以添加它。
6. 您可以验证已添加到“签名与能力”列表中的**声明的年龄范围**。

移除年龄范围模块¶

请参考Podfile示例代码并删除与App Store责任法相关的内容：

target 'HIVE_GAME_COOL' do
end

SDK Cocos2d-x Android¶

与SDK原生Android相同。

SDK Cocos2d-x iOS¶

与SDK Native iOS相同。

SDK Unity Android¶

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

点击 Hive > ExternalDependency 菜单。
在市场设置下检查支持的市场的年龄范围 [Market] 项。AgeRange 模块需要您想要支持的市场模块。

※ 如果您不想使用年龄范围模块，请取消选中。
如果您不使用年龄范围 Google 和 Apple 年龄范围模块，可以取消选中。包含 Amazon AppStore 模块时，年龄范围 Amazon 模块会自动包含。

SDK Unity iOS¶

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

从Unity顶部菜单中选择**Hive**。
选择**构建项目后处理设置 > iOS**。
在Hive后处理编辑器(iOS)中选择**年龄范围**复选框。
在**iOS项目导出**后，您可以验证添加到**签名与功能**列表中的**声明年龄范围**。

SDK 虚幻引擎安卓¶

在Android目标的虚幻引擎环境中使用年龄范围模块，请按以下顺序进行配置：

选择虚幻编辑器 → 编辑 → 项目设置菜单。
从项目设置左侧面板中选择 Hive SDK → 依赖项 → Android。
检查 Hive 模块 → 启用年龄范围。

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

SDK 虚幻引擎 iOS¶

在 iOS 目标的虚幻引擎环境中使用年龄范围模块，请按以下顺序进行配置：

选择虚幻编辑器 → 编辑 → 项目设置。
从项目设置左侧面板中选择 Hive SDK → 依赖项 → iOS。
检查 Hive 模块 → 启用年龄范围。
如果您不想在应用中使用年龄范围模块，请取消勾选。

在虚幻引擎环境中，通过以下*权限模板*添加声明的年龄范围权限。将键值添加到您正在使用的权限模板文件中：

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

如果您没有使用模板，请参考/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 请求用户年龄范围的示例代码如下：

UnityC++KotlinJavaSwiftObjective-C虚幻引擎

API 参考: Unity®

using hive;

AuthV4.getAgeRange((ResultAPI result, AgeRange ageRange) => {    
    if (result.isSuccess()) {    
        // API call success    
    }    
});

API 参考: C++

#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    
    }
});

API 参考: Kotlin

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 调用成功
        } 
    }
})

API 参考: Java

import com.hive.AuthV4;
import com.hive.ResultAPI;

AuthV4.getAgeRange((resultApi, ageRange) -> {
    if (result.isSuccess()) {
        // API call success  
    }
});

API 参考: Swift

import HIVEService    

AuthV4Interface.getAgeRange() { result, ageRange in    
    if result.isSuccess() {    
        // API call success    
    }    
}

API 参考: Objective-C

#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)¶

在苹果应用商店调用getAgeRange API时，会显示一个弹出窗口请求共享年龄范围。

只有选择共享其年龄范围的用户才能验证其年龄范围和批准状态，如果他们拒绝，则会收到REQUIRED状态。

getAgeRange API 响应数据¶

getAgeRange API 响应字段的描述如下。您可以使用每个字段值来提供适合年龄的游戏流程。

响应值可能会变化。如果您想要最新的值，请在应用程序打开时请求API响应。

响应字段	值	描述
`userState`	VERIFIED	用户年龄为18岁或以上。
	SUPERVISED	用户拥有一个监督账户，家长已设置年龄。使用 `ageLower` 和 `ageUpper` 验证用户的年龄范围。
	SUPERVISED_APPROVAL_PENDING	用户拥有一个监督账户，监督的家长尚未批准一个或多个待处理的重要更改。使用 `ageLower` 和 `ageUpper` 验证用户的年龄范围。使用 `mostRecentApprovalDate` 检查最后批准的重要更改。
	SUPERVISED_APPROVAL_DENIED	用户拥有一个监督账户，监督用户的家长拒绝批准一个或多个重要更改。使用 `ageLower`、`ageUpper` 和 `mostRecentApprovalDate` 检查最后批准的重要更改。
	UNKNOWN	不受年龄验证的限制。这可能是适用管辖区和地区以外的用户，或者他们可能是18岁或以上或以下。在“控制台 > 配置 > SDK 设置”中将“用户年龄验证”设置为“不进行验证”将导致 `UNKNOWN` 响应。
	REQUIRED	用户在适用的管辖区和地区尚未经过验证或监督。这些用户可能是18岁或以上或以下。要进行年龄验证，请要求用户访问设备设置和市场应用程序以验证他们的状态。
`ageLower`	0到18	监督用户年龄范围的下限（包含）。使用 `ageLower` 和 `ageUpper` 验证用户的年龄范围。
	-1	`userState` 为 UNKNOWN 或 REQUIRED。
`ageUpper`	2到18	监督用户年龄范围的上限（包含）。使用 `ageLower` 和 `ageUpper` 验证用户的年龄范围。
	-1	用户年龄为18岁或以上，或 `userState` 为 UNKNOWN 或 REQUIRED。
`mostRecentApprovalDate`	日期戳	最近批准的重要更改的日期。例如：“2023-07-01T00:00:00.008Z” 苹果应用商店不支持。
	空（空值）	`userState` 为 SUPERVISED 且未提交任何重要更改。或者 `userState` 为 UNKNOWN 或 REQUIRED。苹果应用商店不支持。
`ageRangeId`	应用商店生成的ID	由市场生成的字母数字ID。 Google Play 商店 : 由 Google Play 分配给监督用户安装的 ID，即 `installID`。用于通知应用批准撤销。请查看应用批准撤销文档。亚马逊应用商店 : 亚马逊账户的 `userId`。苹果应用商店 : 不支持。
	空（空值）	`userState` 为 UNKNOWN 或 REQUIRED。苹果应用商店不支持。

应用内重要变更通知和批准请求¶

根据某些司法管辖区和地区的规定，当游戏应用程序发生以下变化时，游戏应用程序方必须通知家长这些变化，并请求未成年人继续使用该应用程序的批准：

收集、存储或共享的数据的更改
年龄评级更改
新的应用内购买或广告功能的添加
用户体验的更改等。

游戏应用程序端可以决定何时通知更改并请求批准。各个市场通知更改的方法如下：

Google Play 和 Amazon Appstore: 通过各个市场运营的开发者控制台进行通知
Apple App Store: 通过在游戏应用中调用 showAgeRangeUpdatePermission API 进行直接通知

showAgeRangeUpdatePermission API¶

对于分发到 Apple App Store 市场的应用程序，请直接在应用中调用 showAgeRangeUpdatePermission API，以通知父母重要的变更并请求批准。

Note

在编写传递给 showAgeRangeUpdatePermission API 的 description 参数时，请使用简洁易懂的语言，以便父母能够清楚地理解应用中发生了什么变化。父母将根据此参数描述做出批准决定。

调用showAgeRangeUpdatePermission API的示例代码如下：

UnityC++KotlinJavaSwiftObjective-C虚幻引擎

API 参考: Unity®

using hive;

String description = "此更新添加了视频通话和位置共享功能。";

AuthV4.showAgeRangeUpdatePermission(description, (ResultAPI result, AgeRange ageRange) => {    
    if (result.isSuccess()) {    
        // API call success    
    }    
});

API 参考: C++

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
using namespace std;
using namespace hive;

std::string description = "此更新添加了视频通话和位置共享功能。";

AuthV4::showAgeRangeUpdatePermission(description, [=](ResultAPI const & result, AgeRange const & ageRange) {
    if (result.isSuccess()) {    
        // API call success    
    }    
});

API 参考: Kotlin

import com.hive.AuthV4;
import com.hive.ResultAPI;

val description: String = "此更新添加了视频通话和位置共享功能。"

AuthV4.showAgeRangeUpdatePermission(description, object : AuthV4.AuthV4GetAgeRangeListener {
    override fun onAuthV4GetAgeRange(result: ResultAPI, ageRange: AuthV4.AgeRange?) {
        if (result.isSuccess) {    
            // API 调用成功
        } 
    }
})

API 参考: Java

import com.hive.AuthV4;
import com.hive.ResultAPI;

String description = "此更新添加了视频通话和位置共享功能。";

AuthV4.showAgeRangeUpdatePermission(description, (resultApi, ageRange) -> {
    if (result.isSuccess()) {
        // API call success  
    }
});

API 参考: Swift

import HIVEService    

let description = "此更新添加了视频通话和位置共享功能。"

AuthV4Interface.showAgeRangeUpdatePermission(description) { result, ageRange in    
    if result.isSuccess() {    
        // API call success    
    }    
}

API 参考: Objective-C

#import <HIVEService/HIVEService-Swift.h>

NSString *description = "此更新添加了视频通话和位置共享功能。";

[HIVEAuthV4 showAgeRangeUpdatePermission: description handler:^(HIVEResultAPI *result, HIVEAgeRange *ageRange) {
    if ([result isSuccess]) {
        // API call success    
    }    
}];

#include "HiveAuthV4.h"

FString Description = TEXT("此更新添加了视频通话和位置共享功能。");

FHiveAuthV4::ShowAgeRangeUpdatePermission(Description, FHiveAuthV4OnShowAgeRangeUpdatePermissionDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveAuthV4AgeRange& AgeRange) {
    if (Result.IsSuccess()) {
            // 调用成功
    }
}));

撤销家长批准通知¶

家长可以在给予批准后撤回对应用内重要变更通知的批准。当批准被撤回时，未成年人将无法再访问该应用。

当父母的批准被撤销时，通过每个市场检查撤销通知的方法如下：

Google Play：从年龄信号页面下载installID列表以确认撤销。
- Google Play的installID有效期为3个月，之后将被删除。
Apple App Store：发送关于批准撤销的通知。
Amazon Appstore：从开发者控制台的报告部分下载Amazon userId以了解撤销情况。

年龄范围测试¶

Hive SDK 提供了一个测试环境和测试用例，无论是否实施年龄验证法，在请求 getAgeRange API 时都可以接收正常响应。

年龄范围测试环境和测试用例仅在Android目标开发环境中可用，并且可以通过调试模式设置模拟API操作。

Note

要在 iOS 目标开发环境中测试年龄范围功能，您可以使用 Apple 提供的沙盒测试工具。通过使用 Apple 沙盒帐户登录进行测试。

调试模式使用设置¶

要在 Android 目标开发环境中设置调试模式，请运行以下命令。调试模式在 Hive ZoneType.SANDBOX 中运行。

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

调试模式设置应仅用于单元测试或集成测试，以验证游戏应用程序中的操作。

测试用例的数据响应¶

在 Android 目标开发环境中设置调试模式后，Google Play 商店为每个测试用例返回的数据响应如下：

测试用例	用户状态	年龄下限	年龄上限	最近批准日期	年龄范围ID	描述
`1`	已验证	18	-1	空	空	针对年龄已验证的18岁及以上用户的响应。
`2`	需要	-1	-1	空	空	针对无法确认年龄验证和同意状态的用户的响应。
`3`	监督	0	12	2026-01-01T07:00:00.008+0900	550e8400-e29b-41d4-a716-446655441111	针对0至12岁（含）的用户的响应。
`4`	监督	13	15	2026-01-01T07:00:00.008+0900	550e8400-e29b-41d4-a716-446655441111	针对13至15岁（含）的用户的响应。
`5`	监督	16	17	2026-01-01T07:00:00.008+0900	550e8400-e29b-41d4-a716-446655441111	针对16至17岁（含）的用户的响应。
`6`	监督_批准被拒绝	0	12	2026-01-01T07:00:00.008+0900	550e8400-e29b-41d4-a716-446655441111	针对未满18岁且同意待定或未给予的用户的响应。
`7`	未知	-1	-1	空	空	针对所有年龄验证法律不适用的情况的响应。
`8`	未知	-1	-1	空	空	当API返回ResultAPI.RESPONSE_FAIL状态时的响应。(APP_NOT_OWNED)
`9`	未知	-1	-1	空	空	当API返回ResultAPI.RESPONSE_FAIL状态时的响应。(CLIENT_TRANSIENT_ERROR)
`10`	未知	-1	-1	空	空	当API返回ResultAPI.RESPONSE_FAIL状态时的响应。(INTERNAL_ERROR)
`11`	未知	-1	-1	空	空	当API返回ResultAPI.RESPONSE_FAIL状态时的响应。(API_NOT_AVAILABLE)

Appstore

年龄范围操作概述¶

按市场划分的操作流程¶

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

SDK 原生 Android¶

添加年龄范围模块¶

移除年龄范围模块¶

SDK 原生 iOS¶

添加年龄范围模块¶

移除年龄范围模块¶

SDK Cocos2d-x Android¶

SDK Cocos2d-x iOS¶

SDK Unity Android¶

SDK Unity iOS¶

SDK 虚幻引擎 安卓¶

SDK 虚幻引擎 iOS¶

请求用户年龄范围和批准状态¶

调用 getAgeRange API¶

当 getAgeRange API 调用成功时¶

当 getAgeRange API 调用失败时¶

getAgeRange API 调用响应示例 (Apple App Store)¶

getAgeRange API 响应数据¶

应用内重要变更通知和批准请求¶

showAgeRangeUpdatePermission API¶

撤销家长批准通知¶

年龄范围测试¶

调试模式使用设置¶

测试用例的数据响应¶

SDK 虚幻引擎安卓¶