ข้อกำหนดการปฏิบัติตามกฎหมายเพิ่มเติม

Hive SDK มีโมดูล Age range สำหรับตรวจสอบอายุผู้ใช้เพื่อรองรับกฎหมายคุ้มครองผู้เยาว์ เช่น App Store Responsibility Act และกฎหมาย ECA ของบราซิล เมื่อข้อกำหนดการตรวจสอบอายุเริ่มมีผลบังคับใช้ นักพัฒนาที่เผยแพร่แอปผ่านมาร์เก็ตเพลสสามารถใช้โมดูล Age range เพื่อตรวจสอบช่วงอายุผู้ใช้และขอความยินยอมจากผู้ปกครองได้

หากต้องการตรวจสอบช่วงอายุผู้ใช้บน iOS ต้องมีเงื่อนไขต่อไปนี้

• Xcode 26.2 ขึ้นไป
• รองรับฟีเจอร์บน iOS 26.2 ขึ้นไป

คู่มือนี้อธิบายภาพรวมการทำงาน วิธีใช้งาน และวิธีทดสอบของโมดูล Age range ใน Hive SDK

ภาพรวมการทำงานของ 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¶

เพื่อเตรียมการใช้โมดูล Age Range ให้เพิ่มหรือลบโมดูล Age Range ตามเอนจิน SDK การพัฒนาและระบบปฏิบัติการเป้าหมายแต่ละอย่าง

SDK Native Android¶

เพิ่มโมดูล Age Range¶

1. ตั้งค่าตลาดดิจิทัลใน การตั้งค่า SDK ทั่วไป
2. เพิ่มรายการต่อไปนี้ในไฟล์ build.gradle ระดับโมดูล:

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

ลบโมดูล Age Range¶

ลบรายการต่อไปนี้จากไฟล์ build.gradle ระดับโมดูล:

// App Store Accountability Law compliance - Google
// implementation "com.com2us.android.hive:hive-agerange-google-agesignals" // ลบบรรทัดนี้เมื่อไม่ใช้

SDK Native iOS¶

เพิ่มโมดูล Age Range¶

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. เพิ่มสิทธิ์ Declared Age Range ในสภาพแวดล้อม SDK Native iOS ในลำดับต่อไปนี้:

   1. เลือกโปรเจ็กต์ผู้พัฒนาของคุณในตัวนำทางโปรเจ็กต์ของหน้าต่างโปรเจ็กต์ Xcode
   2. เลือกแอปผู้พัฒนาของคุณจากรายการ TARGETS
   3. คลิกแท็บ Signing & Capabilities
   4. คลิกปุ่ม + Capability ที่มุมบนซ้ายของแท็บ Signing & Capabilities
   5. เลือก Declared Age Range จากรายการเพื่อเพิ่มเข้าไป
   6. คุณสามารถตรวจสอบ Declared Age Range ที่เพิ่มในรายการ Signing & Capabilities

ลบโมดูล Age Range¶

อ้างอิง ตัวอย่างรหัส Podfile และลบเนื้อหาที่เกี่ยวข้องกับกฎหมายความรับผิดชอบของ App Store:

target 'HIVE_GAME_COOL' do
end

SDK Cocos2d-x Android¶

เหมือนกับ SDK Native Android

SDK Cocos2d-x iOS¶

เหมือนกับ SDK Native iOS

SDK Unity Android¶

เพื่อใช้โมดูล Age Range ในสภาพแวดล้อม Unity เป้าหมาย Android ให้กำหนดค่าในลำดับต่อไปนี้:

1. คลิกเมนู Hive > ExternalDependency

2. ตรวจสอบรายการ Age Range [Market] สำหรับตลาดดิจิทัลที่รองรับภายใต้ Market Settings โมดูล AgeRange ต้องใช้โมดูลตลาดดิจิทัลที่คุณต้องการรองรับ

   ※ ยกเลิกการตรวจสอบหากคุณไม่ต้องการใช้โมดูล Age Range
   คุณสามารถยกเลิกการตรวจสอบหากคุณไม่ใช้โมดูล AgeRange Google และ Apple AgeRange โมดูล Age Range Amazon และ Age Range Samsung จะรวมอยู่โดยอัตโนมัติเมื่อคุณรวมแต่ละโมดูลตลาดดิจิทัลระดับสูงกว่า

SDK Unity iOS¶

System API ที่เกี่ยวข้องกับกฎหมายความรับผิดชอบของ App Store รองรับเฉพาะบน iOS 26.2 ขึ้นไปเท่านั้น

1. คลิกเมนู [Hive > ExternalDependency]

2. ใต้การตั้งค่า Market Settings ให้เลือกช่อง Age Range [Market] ของมาร์เก็ตที่รองรับ โมดูล Age Range จำเป็นต้องใช้โมดูลมาร์เก็ตที่ต้องการรองรับ

   ※ หากไม่ต้องการใช้โมดูล Age Range ให้ยกเลิกการเลือก
   หากไม่ใช้โมดูล Age Range Apple และ Age Range Permission Apple คุณสามารถยกเลิกการเลือกได้

เพื่อใช้โมดูล Age Range ในสภาพแวดล้อม Unity เป้าหมาย iOS ให้เพิ่มสิทธิ์ Declared Age Range ในลำดับต่อไปนี้ คุณสามารถกำหนดค่าได้อย่างง่ายดายด้วยเอดิเตอร์ Unity

1. เลือก Hive จากเมนูด้านบนของ Unity
2. เลือก Build project post process setting > iOS
3. ใน Hive PostProcess Editor(iOS) ให้เลือกช่องทำเครื่องหมาย Age Range
4. หลังจาก iOS project export แล้ว คุณสามารถตรวจสอบ Declared Age Range ที่เพิ่มในรายการ Signing & Capabilities ได้

SDK Unreal Engine Android¶

เพื่อใช้โมดูล Age Range ในสภาพแวดล้อม Unreal Engine เป้าหมาย Android ให้กำหนดค่าในลำดับต่อไปนี้:

1. เลือกเมนู Unreal Editor → Edit → Project Settings
2. เลือก Hive SDK → Dependency → Android จากแผงด้านซ้าย Project Settings

3. ตรวจสอบ Hive Module → Enable AgeRange

   ※ ยกเลิกการตรวจสอบหากคุณไม่ต้องการใช้โมดูล AgeRange

SDK Unreal Engine iOS¶

เพื่อใช้โมดูล Age Range ในสภาพแวดล้อม Unreal Engine เป้าหมาย iOS ให้กำหนดค่าในลำดับต่อไปนี้:

1. เลือก Unreal Editor → Edit → Project Settings
2. เลือก Hive SDK → Dependency → iOS จากแผงด้านซ้าย Project Settings

3. ตรวจสอบ Hive Module → Enable AgeRange

   ※ ยกเลิกการตรวจสอบหากคุณไม่ต้องการใช้โมดูล AgeRange

4. ในสภาพแวดล้อม Unreal Engine ให้แก้ไขไฟล์ IOSExport.cs เพื่อเพิ่มสิทธิ์ Declared Age Range
   ในไฟล์ 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 ของคุณ ให้เพิ่มสิทธิ์ Declared Age Range โดยใช้เทมเพลต .entitlements_ ดังแสดงด้านล่าง เพิ่มคีย์-ค่าลงในเทมเพลต _.entitlements ที่มีอยู่ของคุณ

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

entitlements 템플릿이 없다면, Plugins/HIVESDK/Source/HiveSDKiOS/template/ 경로 하위의 HIVESDKV4Tester.entitlements 파일을 참고할 수 있습니다.

ขอ Age Range และสถานะการอนุมัติของผู้ใช้¶

เรียก getAgeRange API ในแอปที่ทำงานเพื่อตรวจสอบอายุของผู้ใช้และสถานะการอนุมัติจากผู้ปกครอง นอกจากกฎหมายที่ควบคุมโดยการปฏิบัติตามข้อกำหนดนี้แล้ว หากแอปมีกระบวนการตรวจสอบอายุแยกต่างหาก ขอแนะนำให้เรียก getAgeRange API ก่อนเพื่อตรวจสอบอายุ

เมื่อคุณเรียก getAgeRange API ข้อมูลสถานะ userState และ Age Range ของผู้ใช้ที่อาศัยอยู่ในภูมิภาคที่อยู่ภายใต้กฎหมายการตรวจสอบอายุจะถูกส่งคืนเป็นการตอบสนอง Age Ranges เริ่มต้นที่ส่งคืนสำหรับเขตอำนาจศาลที่ใช้ได้มีดังต่อไปนี้และอาจเปลี่ยนแปลงตามข้อกำหนดของภูมิภาค:

• 0~12 ปี
• 13~15 ปี
• 16~17 ปี
• 18 ปีขึ้นไป

เรียก getAgeRange API¶

ต่อไปนี้เป็นตัวอย่างโค้ดสำหรับการเรียก getAgeRange API เพื่อขอ age range ของผู้ใช้

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 : เรียก showAgeRangeUpdatePermission API เฉพาะสำหรับเกมที่แจกจ่ายบน Apple App Store เท่านั้น
• 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 บน Apple App Store จะแสดงป๊อปอัปขอการแชร์ age range

เฉพาะผู้ใช้ที่เลือกแชร์ age range ของตนเท่านั้นที่สามารถตรวจสอบ age range และสถานะการอนุมัติได้ หากปฏิเสธ จะได้รับสถานะ REQUIRED

ข้อมูลการตอบสนอง getAgeRange API¶

คำอธิบายของฟิลด์การตอบสนอง getAgeRange API มีดังต่อไปนี้ คุณสามารถจัดหากระบวนการเกมตามอายุโดยใช้ค่าของแต่ละฟิลด์

ค่าการตอบสนองอาจเปลี่ยนแปลง เพื่อให้ได้ค่าล่าสุด ให้ขอการตอบสนอง API เมื่อแอปเปิด

การแจ้งเตือนการเปลี่ยนแปลงในแอปที่สำคัญและคำขอการอนุมัติ¶

ตามกฎระเบียบในเขตอำนาจศาลและภูมิภาคบางแห่ง เมื่อการเปลี่ยนแปลงต่อไปนี้เกิดขึ้นในแอปเกม แอปเกมจะต้องแจ้งผู้ปกครองหรือผู้ดูแลเกี่ยวกับการเปลี่ยนแปลงและขอการอนุมัติให้ผู้เยาว์ใช้แอปต่อไป

• การเปลี่ยนแปลงข้อมูลที่ถูกเก็บรวบรวม จัดเก็บ หรือแชร์
• การเปลี่ยนแปลงเรตติ้งอายุ
• การเพิ่มคุณสมบัติการซื้อในแอปใหม่หรือคุณสมบัติโฆษณา
• การเปลี่ยนแปลงประสบการณ์ผู้ใช้ เป็นต้น

แอปเกมสามารถกำหนดเวลาที่จะแจ้งการเปลี่ยนแปลงและขอการอนุมัติได้ วิธีการแจ้งการเปลี่ยนแปลงสำหรับตลาดแต่ละแห่งมีดังต่อไปนี้:

• Google Play และ Amazon Appstore, Samsung Galaxy Store: การแจ้งผ่านคอนโซลนักพัฒนาที่ดำเนินการโดยตลาดแต่ละแห่ง
• Apple App Store: การแจ้งโดยการเรียก showAgeRangeUpdatePermission API โดยตรงจากแอปเกม

ShowAgeRangeUpdatePermission API¶

หากเป็นแอปที่เผยแพร่ใน Apple App Store ให้เรียกใช้ API showAgeRangeUpdatePermission จากแอปโดยตรงเพื่อแจ้งการเปลี่ยนแปลงสำคัญแก่ผู้ปกครอง (พ่อแม่) และขอการอนุมัติ

ตั้งแต่ Hive SDK 26.3.4 เป็นต้นไป หากต้องการใช้ API showAgeRangeUpdatePermission ต้องเพิ่มโมดูล HiveAgeRangePermissionApple สำหรับรายละเอียดเพิ่มเติม โปรดดูหัวข้อ SDK Native iOS

ต่อไปนี้เป็นตัวอย่างโค้ดสำหรับการเรียก 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
    }
}));

การแจ้งการเพิกถอนการอนุมัติจากผู้ปกครอง¶

แม้ว่าผู้ปกครองหรือผู้ดูแลจะอนุมัติการแจ้งการเปลี่ยนแปลงสำคัญในแอปแล้ว พวกเขาสามารถยกเลิกการอนุมัติภายหลังได้ หากการอนุมัติถูกเพิกถอน ผู้ใช้เยาว์จะไม่สามารถเข้าถึงแอปได้อีกต่อไป

เมื่อผู้ปกครองหรือผู้ดูแลเพิกถอนการอนุมัติ วิธีตรวจสอบการแจ้งการเพิกถอนผ่านตลาดแต่ละแห่งมีดังต่อไปนี้:

• Google Play: คุณสามารถยืนยันการเพิกถอนโดยการดาวน์โหลดรายการ installID จากหน้า Age Signals * installID ของ Google Play มีอายุการใช้งาน 3 เดือนและจะถูกลบหลังจากนั้น
• Apple App Store: ส่ง การแจ้งเกี่ยวกับการเพิกถอนการอนุมัติ
• Amazon Appstore: คุณสามารถยืนยันการเพิกถอนโดยการดาวน์โหลด Amazon userId จากส่วนรายงานในคอนโซลนักพัฒนา
• Samsung Galaxy Store: เนื่องจากไม่มีการแจ้งเตือนแยกต่างหากเมื่อมีการเพิกถอนการอนุมัติของผู้ปกครอง คุณสามารถเรียก API getAgeRagne และตรวจสอบจากค่าสถานะที่ส่งกลับมาได้

การทดสอบ Age range¶

Hive SDK จัดหาสภาพแวดล้อมการทดสอบและกรณีทดสอบที่ช่วยให้คุณได้รับการตอบสนองปกติเมื่อขอ getAgeRange API โดยไม่ขึ้นอยู่กับว่ากฎหมายการตรวจสอบอายุได้ถูกนำมาใช้แล้วหรือไม่

สภาพแวดล้อมการทดสอบ Age Range และกรณีทดสอบใช้ได้เฉพาะในสภาพแวดล้อมการพัฒนาเป้าหมาย Android เท่านั้น และคุณสามารถจำลองพฤติกรรม API ผ่านการตั้งค่าโหมดดีบัก

เปิดใช้งานโหมดดีบัก¶

เพื่อตั้งค่าโหมดดีบักในสภาพแวดล้อมการพัฒนาเป้าหมาย Android ให้รันคำสั่งต่อไปนี้ โหมดดีบักทำงานใน Hive ZoneType.SANDBOX

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

ใช้การตั้งค่าโหมดดีบักเฉพาะสำหรับการทดสอบหน่วยย่อยหรือการทดสอบการรวมระบบเพื่อตรวจสอบพฤติกรรมในแอปเกม

การตอบสนองข้อมูลตามกรณีทดสอบ¶

หลังจากตั้งค่าโหมดดีบักในสภาพแวดล้อมการพัฒนาเป้าหมาย Android การตอบสนองข้อมูลที่ส่งคืนโดย Google Play Store สำหรับแต่ละกรณีทดสอบมีดังต่อไปนี้: