Appstore

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

คู่มือนี้อธิบายวิธีการทำงาน การใช้งาน และวิธีการทดสอบของโมดูล Age Range ที่จัดเตรียมโดย Hive SDK.

ภาพรวมการดำเนินงานช่วงอายุ¶

ฟีเจอร์ที่มีให้โดยโมดูลช่วงอายุมีดังนี้:

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

การไหลของการดำเนินงานตามตลาด¶

การไหลของการดำเนินงานของโมดูลช่วงอายุโดยตลาดมีดังนี้:

• Google Play และ Amazon Appstore

• Apple App Store

[การเตรียมการ] เพิ่มโมดูลช่วงอายุ¶

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

SDK Native Android¶

เพิ่มโมดูลช่วงอายุ¶

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

   // การปฏิบัติตามกฎหมายความรับผิดชอบของ App Store - 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 Native iOS¶

เพิ่มโมดูลช่วงอายุ¶

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

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

2. เพิ่มสิทธิ์ช่วงอายุที่ประกาศในสภาพแวดล้อม SDK Native iOS ตามลำดับต่อไปนี้:

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

ลบโมดูลช่วงอายุ¶

อ้างอิงจาก ตัวอย่างโค้ด 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¶

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

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

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

SDK Unity iOS¶

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

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

SDK Unreal Engine Android¶

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

1. เลือก Unreal Editor → แก้ไข → เมนูการตั้งค่าโปรเจกต์
2. เลือก Hive SDK → การพึ่งพา → Android จากแผงด้านซ้ายของการตั้งค่าโปรเจกต์

3. ตรวจสอบ Hive Module → เปิดใช้งาน AgeRange.

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

SDK Unreal Engine iOS¶

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

1. เลือก Unreal Editor → แก้ไข → การตั้งค่าโปรเจกต์
2. เลือก Hive SDK → ความขึ้นอยู่กับ → iOS จากแผงด้านซ้ายของการตั้งค่าโปรเจกต์
3. ตรวจสอบ Hive Module → เปิดใช้งาน AgeRange.
4. ยกเลิกการเลือกหากคุณไม่ต้องการใช้โมดูล AgeRange ในแอป

ในสภาพแวดล้อมของ Unreal Engine ให้เพิ่มสิทธิ์ Declared Age Range ผ่าน เทมเพลตสิทธิ์ ต่อไปนี้ เพิ่มค่าคีย์ลงในไฟล์เทมเพลตสิทธิ์ที่คุณกำลังใช้:

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

หากคุณไม่ได้ใช้เทมเพลต ให้ดูที่ไฟล์ /Plugins/HIVESDK/Source/HiveSDKiOS/template/HIVESDKV4Tester.entitlements

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

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

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

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

เรียก API getAgeRange¶

โค้ดตัวอย่างสำหรับการเรียกใช้ API getAgeRange เพื่อขอช่วงอายุของผู้ใช้มีดังนี้:

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 call success    
    }    
}];

#include "HiveAuthV4.h"

FHiveAuthV4::GetAgeRange(FHiveAuthV4OnGetAgeRangeDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveAuthV4AgeRange& AgeRange) {
    if (Result.IsSuccess()) {
            // 호출 성공
    }
}));

เมื่อการเรียก API getAgeRange สำเร็จ¶

หลังจากที่ขอ API getAgeRange ในแอปเกมแล้ว การดำเนินการของแอปเกมตามค่าการตอบกลับ userState มีดังนี้:

• หนึ่งใน UNKNOWN, VERIFIED, SUPERVISED : ดำเนินการกับแอปและจัดเตรียมเนื้อหาที่เหมาะสมกับอายุ
  • เมื่อ SUPERVISED และแจ้งการเปลี่ยนแปลงที่สำคัญภายในแอป : เรียกใช้ API showAgeRangeUpdatePermission เฉพาะสำหรับเกมที่จัดจำหน่ายใน Apple App Store
• SUPERVISED_APPROVAL_PENDING หรือ SUPERVISED_APPROVAL_DENIED :
  • การอนุมัติจากผู้ปกครองสำหรับคำขอของผู้เยาว์ในการใช้แอปยังอยู่ระหว่างรอการอนุมัติหรือถูกปฏิเสธแล้ว อายุสามารถตรวจสอบได้และแอปสามารถดำเนินการต่อได้
• REQUIRED : อายุของผู้ใช้ยังไม่ได้รับการตรวจสอบในเขตอำนาจศาลและภูมิภาคที่เกี่ยวข้อง แนะนำผู้ใช้ให้แชร์ข้อมูลอายุในแอปตลาดหรือการตั้งค่าอุปกรณ์เพื่ออนุญาตให้มีการตรวจสอบอายุในแอป

เมื่อการเรียก API getAgeRange ล้มเหลว¶

หลังจากที่ขอ API getAgeRange ในแอปเกม หากการเรียกล้มเหลว จะได้รับรหัสความล้มเหลวของ ResultAPI ดังต่อไปนี้:

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

ข้อผิดพลาดในการเรียก API อาจเกิดขึ้นได้จากหลายสาเหตุ เช่น การใช้แอปตลาดที่ไม่ใช่เวอร์ชันล่าสุด

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

ตัวอย่างการตอบกลับ API getAgeRange (Apple App Store)¶

เมื่อเรียกใช้ API getAgeRange บน Apple App Store จะมีป๊อปอัปแสดงขึ้นเพื่อขอการแชร์ช่วงอายุ

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

ข้อมูลการตอบกลับ API getAgeRange¶

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

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

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

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

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

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

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

showAgeRangeUpdatePermission API¶

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

โค้ดตัวอย่างสำหรับการเรียกใช้ API showAgeRangeUpdatePermission มีดังนี้:

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()) {
            // 호출 성공
    }
}));

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

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

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

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

การทดสอบช่วงอายุ¶

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

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

การตั้งค่าใช้งานโหมดดีบัก¶

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

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

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

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

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