未成年人保護法合規

Hive SDK 提供 Age range 模組，用於在未成年人保護相關法規（如 App Store Responsibility Act 與巴西 ECA）下驗證使用者年齡。 隨著強制年齡驗證法規逐步施行，透過商店分發應用程式的開發者可套用 Age range 模組，確認使用者年齡範圍並請求監護人同意。

若要在 iOS 上進行使用者年齡範圍確認，需滿足以下條件。

• Xcode 26.2 以上
• 功能於 iOS 26.2 以上提供

本指南說明 Hive SDK 提供的 Age range 模組之運作方式、使用方法與測試方法。

Age range 運作概述¶

Age range 模組提供的功能如下：

• 使用者年齡範圍與同意狀態查詢
  • getAgeRange API
• 應用內重大變更通知與同意請求
  • showAgeRangeUpdatePermission API (僅限 Apple App Store)
  • 監護人同意撤銷通知

各商店流程¶

Age range 模組依商店的流程如下：

• Google Play

• Amazon Appstore、Samsung Galaxy Store

• Apple App Store

事前準備：新增 Age range 模組¶

作為使用年齡範圍模組的準備，根據每個 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}'
         # 26.3.4 之後可選擇套用「應用程式內重要變更通知與核准請求」
         pod 'HiveAgeRangePermissionApple', '${SDK_VERSION}'  # (26.3.4+ Optional)
   end
   

2. 在SDK原生iOS環境中按以下順序添加已聲明的年齡範圍權限：

   1. 在Xcode項目窗口的項目導航器中選擇您的開發者項目。
   2. 從TARGETS列表中選擇您的開發者應用程序。
   3. 點擊Signing & Capabilities標籤。
   4. 點擊Signing & Capabilities標籤左上角的**+ Capability**按鈕。
   5. 從列表中選擇**Declared Age Range**以添加它。
   6. 您可以驗證已添加到Signing & Capabilities列表中的**Declared Age Range**。

移除年齡範圍模組¶

請參考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¶

與 App Store 責任法相關的系統 API 僅支援 iOS 26.2 以上。

1. 按一下 [Hive > ExternalDependency] 選單。

2. 在 Market Settings 設定下，勾選支援市場的 Age Range [Market] 項目。Age Range 模組需要您要支援的市場模組。

   ※ 若不使用 Age Range 模組，請取消勾選。
   若不使用 Age Range Apple 與 Age Range Permission Apple 模組，即可取消勾選。

要在 iOS 目標 Unity 環境中使用年齡範圍模組，請按照以下順序添加已聲明的年齡範圍權限。您可以輕鬆地使用 Unity 編輯器進行配置。

1. 从 Unity 顶部菜单中选择 Hive。
2. 选择 构建项目后处理设置 > iOS。
3. 在 Hive PostProcess Editor(iOS) 中選取 Age Range 核取方塊。
4. 在 iOS project export 後，可在 Signing & Capabilities 清單中確認新增的 Declared Age Range。

SDK 虛幻引擎 Android¶

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

1. 選擇 Unreal Editor → 編輯 → 專案設定 菜單。
2. 從專案設定左側面板中選擇 Hive SDK → 依賴性 → Android。

3. 檢查 Hive 模組 → 啟用年齡範圍。

   ※ 如果您不想使用年齡範圍模組，請取消勾選。

SDK Unreal Engine iOS¶

在 iOS 目標的 Unreal Engine 環境中使用年齡範圍模組，請按照以下順序進行配置：

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

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

   ※ 如果您不想使用 AgeRange 模組，請取消勾選。

4. 在虛幻引擎環境中，修改 IOSExport.cs 文件以添加已聲明的年齡範圍權限。
   在 Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExport.cs 文件中，添加位於 'Add' 和 'Add End' 之間的行。

   虛幻引擎

   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 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 呼叫成功    
        }    
}];

#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 : 用戶的年齡在適用的司法管轄區和地區尚未被驗證。指導用戶在市場應用程式或設備設置中共享年齡信息，以便應用程式能夠驗證年齡。

在獲取年齡範圍 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：通过每个市场运营的开发者控制台进行通知
• Apple App Store：通过游戏应用直接调用 showAgeRangeUpdatePermission API 进行通知

ShowAgeRangeUpdatePermission API¶

若應用程式發佈至 Apple App Store 市場，請在應用程式中直接呼叫 showAgeRangeUpdatePermission API，向監護人（父母）通知重要變更並請求核准。

自 Hive SDK 26.3.4 起，若要使用 showAgeRangeUpdatePermission API，必須新增 HiveAgeRangePermissionApple 模組。詳細內容請參閱 SDK Native iOS 項目。

以下是调用 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 call success
        } 
    }
})

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

String description = "此更新新增了視頻通話和位置共享功能。";

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

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来确认撤销。
• Samsung Galaxy Store: 由於不會另外收到監護人同意撤回通知，因此可呼叫 getAgeRagne API，並透過回傳的狀態值進行確認。

年齡範圍測試¶

Hive SDK 提供了一個測試環境和測試案例，讓您在請求 getAgeRange API 時能夠接收到正常的回應，無論年齡驗證法案是否已實施。

年齡範圍測試環境和測試案例僅在 Android 目標開發環境中可用，您可以通過調試模式設置來模擬 API 行為。

啟用除錯模式¶

要在 Android 目標開發環境中設置調試模式，請運行以下命令。調試模式在 Hive ZoneType.SANDBOX 中運行。

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

僅在單元測試或整合測試中使用調試模式設置，以驗證遊戲應用程式中的行為。

測試案例的數據回應¶

在 Android 目標開發環境中設置調試模式後，Google Play 商店對每個測試案例返回的數據響應如下：