应用商店责任法回应

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

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

年龄范围操作概述¶

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

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

按市场划分的操作流程¶

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

• Google Play 和 Amazon Appstore

• 苹果应用商店

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

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

SDK 原生 Android¶

添加年龄范围模块¶

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

   // 应用商店问责法合规 - 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¶

添加年龄范围模块¶

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

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

2. 在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 环境中使用年龄范围模块，请按以下顺序进行配置：

1. 点击 Hive > ExternalDependency 菜单。

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

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

SDK Unity iOS¶

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

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

SDK 虚幻引擎 安卓¶

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

1. 选择虚幻编辑器 → 编辑 → 项目设置菜单。
2. 从项目设置左侧面板中选择 Hive SDK → 依赖项 → Android。

3. 检查 Hive 模块 → 启用年龄范围。

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

SDK 虚幻引擎 iOS¶

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

1. 选择 Unreal Editor → 编辑 → 项目设置。
2. 从项目设置左侧面板中选择 Hive SDK → 依赖项 → iOS。

3. 检查 Hive 模块 → 启用 AgeRange。

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

在虚幻引擎环境中，修改 IOSExport.cs 文件以添加声明的年龄范围权限。
在 Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExport.cs 文件中，在 'Add' 和 'Add End' 之间添加行。

=== "虚幻引擎"

    ``` cpp
    Text.AppendLine( "<dict>");
    Text.AppendLine( "\t<key>get-task-allow</key>");
    Text.AppendLine(string.Format( "\t<{0}/>", bForDistribution ? "false": "true"));

    // 添加
    // 为使用年龄范围模块所需的项。
    Text.AppendLine("\t<key>com.apple.developer.declared-age-range</key>");
    Text.AppendLine("\t<true/>");
    // 添加结束

        if (bCloudKitSupported) {
                if (iCloudContainerIdentifiersXML != ""
    ```

修改权限模板（虚幻引擎 5）¶

在您的虚幻引擎 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 调用成功
                } 
        }
})

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

AuthV4.getAgeRange((resultApi, ageRange) -> {
        if (result.isSuccess()) {
                // API 调用成功  
        }
});

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

#include "HiveAuthV4.h"

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

成功调用 getAgeRange API 时¶

在游戏应用中请求getAgeRange API后，游戏应用的操作流程根据响应值userState如下：

• UNKNOWN、VERIFIED或SUPERVISED之一：继续使用应用程序并提供适合年龄的内容 * 在SUPERVISED时通知重要的应用内更改：仅对在Apple App Store上分发的游戏调用showAgeRangeUpdatePermission API
• SUPERVISED_APPROVAL_PENDING或SUPERVISED_APPROVAL_DENIED： * 对未成年人继续使用该应用程序的请求的家长批准仍在待定中或已被拒绝。验证年龄并允许应用程序继续。
• REQUIRED：用户的年龄在适用的司法管辖区和地区尚未得到验证。引导用户在市场应用程序或设备设置中共享年龄信息，以便应用程序可以验证年龄。

在获取年龄范围 API 调用失败时¶

在游戏应用中请求getAgeRange API后，如果调用失败，您将收到以下ResultAPI失败代码：

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

API调用错误可能由于多种原因发生，例如使用不是最新版本的市场应用程序。

如果在会话期间发生错误，请采取措施以最小化对用户环境的干扰，例如在超过最大 API 调用重试次数时结束调用。

示例 getAgeRange API 调用响应（Apple App Store）¶

在苹果App Store上调用getAgeRange API时，会弹出请求共享年龄范围的窗口。

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

GetAgeRange API 响应数据¶

getAgeRange API 响应字段的描述如下。您可以利用每个字段值根据年龄提供游戏流程。

响应值可能会发生变化。要获取最新值，请在应用程序打开时请求API响应。

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

根据某些司法管辖区和地区的规定，当游戏应用程序发生以下更改时，游戏应用程序必须通知父母或监护人该更改，并请求批准未成年人继续使用该应用程序。

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

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

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

ShowAgeRangeUpdatePermission API¶

对于在苹果应用商店分发的应用，直接从应用调用showAgeRangeUpdatePermission API，以通知父母或监护人重要的变化并请求批准。

以下是调用 showAgeRangeUpdatePermission API 的示例代码。

using hive;

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

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 = "此更新添加了视频通话和位置共享功能。";

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 = "此更新添加了视频通话和位置共享功能。"

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

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

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

AuthV4.showAgeRangeUpdatePermission(description, (resultApi, ageRange) -> {
    if (result.isSuccess()) {
        // API 调用成功  
    }
});

import HIVEService    

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

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

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

撤销家长批准通知¶

即使在父母或监护人已在应用中批准重要更改通知后，他们也可以稍后取消批准。如果批准被撤销，未成年人将无法再访问该应用。

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

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

年龄范围测试¶

Hive SDK 提供了一个测试环境和测试用例，使您在请求 getAgeRange API 时能够接收到正常的响应，无论是否已实施年龄验证账单。

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

启用调试模式¶

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

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

仅在单元测试或集成测试中使用调试模式设置，以验证游戏应用程序中的行为。

测试用例的数据响应¶

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