ขอสัญญาณอายุ

เอกสารนี้อธิบายวิธีขอสัญญาณอายุโดยใช้ Play Age Signals API

Play Age Signals SDK 0.0.4 มีสถาปัตยกรรมแบบ 2 ฟังก์ชัน ซึ่งออกแบบมาเพื่อลดความซับซ้อนของคำขอสัญญาณอายุและรองรับโมเดล ตามตัวเลือกของผู้ใช้ หากต้องการขอสัญญาณอายุ ให้ใช้เวิร์กโฟลว์ระดับสูงนี้

เรียกใช้เมธอด requestAgeSignalsAccess(Activity) ซึ่งจะแสดงผล ageSignalsStatus ค่าของ ageSignalsStatus อาจเป็น SHARED, NOT_SHARED หรือ VERIFICATION_REQUIRED

  • หาก ageSignalsStatus == NOT_SHARED: แอปจะไม่ได้รับสัญญาณอายุ ในการตอบกลับของ API
  • หาก ageSignalsStatus == SHARED: เรียกใช้เมธอด checkAgeSignals() หากผู้ใช้หรือผู้ปกครองตัดสินใจที่จะแชร์สัญญาณอายุ คุณจะได้รับสัญญาณอายุเป็นส่วนหนึ่งของการตอบกลับจาก API และสามารถตัดสินใจได้ว่าจะจัดการการตอบกลับอย่างไร
  • หากageSignalsStatus == VERIFICATION_REQUIRED: ระบบไม่ทราบอายุของผู้ใช้ และผู้ใช้อยู่ในเขตอำนาจศาลหรือภูมิภาคที่เกี่ยวข้องซึ่งกำหนดให้ต้องมีการยืนยันอายุ และการแชร์สัญญาณอายุ หากต้องการรับสัญญาณอายุจาก Google Play ในภูมิภาคเหล่านี้ ให้ขอให้ผู้ใช้ไปที่ Play Store เพื่อแก้ไขสถานะของตน

requestAgeSignalsAccess(Activity) เมธอดจะแสดงค่าที่แตกต่างกัน ขึ้นอยู่กับว่าการแชร์อายุภาคบังคับมีผลบังคับใช้ในภูมิภาคหรือไม่

  • สำหรับผู้ใช้ที่มีสิทธิ์ในรัฐของสหรัฐอเมริกาที่มีกฎหมายกำหนดให้ App Store ต้องให้ข้อมูลอายุที่ยืนยันแล้วแก่นักพัฒนาแอป ระบบจะไม่ทริกเกอร์ข้อความแจ้งในแอป แต่ระบบจะขอให้ผู้ใช้ยืนยันตัวตนหรือตั้งค่าการควบคุมดูแลเมื่อผู้ใช้ไปที่แอป Play Store ใช้ค่าของ ageSignalsStatus เพื่อกำหนดสถานะการยืนยัน
  • สำหรับผู้ใช้ในภูมิภาคอื่นๆ ที่การแชร์อายุขึ้นอยู่กับตัวเลือกของผู้ใช้หรือ ผู้ปกครอง ให้ทำดังนี้
    • หากการตั้งค่าของผู้ใช้เป็นถามก่อนแชร์ ระบบจะแสดงข้อความแจ้งในแอป หากผู้ใช้ตกลงที่จะแชร์อายุ ค่าของ ageSignalsStatus จะเป็น SHARED แต่หากไม่ตกลงจะเป็น NOT_SHARED
    • หากการตั้งค่าของผู้ใช้เป็นแชร์เสมอ ระบบจะไม่แสดงข้อความแจ้งในแอป และค่าของ ageSignalsStatus จะเป็น SHARED
    • หากการตั้งค่าของผู้ใช้เป็นไม่แชร์ ระบบจะไม่แสดงข้อความแจ้งในแอป และค่าของ ageSignalsStatus จะเป็น NOT_SHARED
    • สำหรับผู้ใช้ที่อยู่ภายใต้การควบคุมดูแล ผู้ปกครองสามารถเลือกแชร์อายุของบุตรหลานในการตั้งค่าแอป Family Link ได้ หากผู้ปกครองเลือกที่จะแชร์อายุ ค่าของ ageSignalsStatus จะเป็น SHARED แต่หากไม่แชร์ ค่าจะเป็น NOT_SHARED

รูปภาพต่อไปนี้แสดงการกำหนดค่าช่วงอายุสำหรับถามก่อนแชร์ในการตั้งค่า Play

เมนูการตั้งค่า Google Play ที่แสดงตัวเลือกสำหรับการแชร์อายุ ได้แก่ ถามก่อนแชร์ แชร์เสมอ และไม่แชร์
รูปที่ 1 จัดการการแชร์อายุในการตั้งค่า Play

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

กล่องโต้ตอบความยินยอมในแอปที่แจ้งให้ผู้ใช้แชร์ช่วงอายุกับแอป
รูปที่ 2 คำขอแชร์ช่วงอายุในแอป

รูปภาพต่อไปนี้แสดงวิธีที่ผู้ใช้จะเปิดหรือปิดใช้การแชร์อายุสำหรับแอปที่เฉพาะเจาะจงได้

กล่องโต้ตอบการตั้งค่าสำหรับแอปหนึ่งๆ ที่แสดงสวิตช์เปิด/ปิดเพื่อเปิดหรือปิดใช้การแชร์ช่วงอายุ
รูปที่ 3 เปิดหรือปิดใช้การแชร์อายุสำหรับแอปที่ต้องการ

ตัวอย่างต่อไปนี้แสดงวิธีขอสัญญาณอายุ

Kotlin

// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
val ageSignalsManager = AgeSignalsManagerFactory.create(applicationContext)

// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
val accessRequest = AgeSignalsAccessRequest.builder()
    .setActivity(this)
    .build()

ageSignalsManager.requestAgeSignalsAccess(accessRequest)
    .addOnSuccessListener { accessResult ->
        if (accessResult.ageSignalsStatus() == AgeSignalsStatus.SHARED) {
            // The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
            // Retrieve the actual age signals.
            retrieveAgeSignals(ageSignalsManager)
        } else {
            // Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
        }
    }
    .addOnFailureListener { exception ->
        // Handle API/Play Store connection and system errors
        handleAgeSignalsError(exception)
    }

private fun retrieveAgeSignals(manager: AgeSignalsManager) {
    // 3. Perform the actual age signals query once sharing is active.
    manager.checkAgeSignals(AgeSignalsRequest.builder().build())
        .addOnSuccessListener { ageSignalsResult ->
            val installId = ageSignalsResult.installId()
            val ageLower = ageSignalsResult.ageLower()
            val ageUpper = ageSignalsResult.ageUpper()
            val significantChangeDate = ageSignalsResult.significantChangeApprovalDate()
            val ageRangeSource = ageSignalsResult.ageRangeSource()

            if (ageLower != null) {
                if (ageUpper != null) {
                    // The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
                } else {
                    // The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
                }
            } else {
                // Both bounds are null: The user is not sharing their age (e.g. they are a verified adult)
            }
        }
        .addOnFailureListener { exception ->
            handleAgeSignalsError(exception)
        }
}

Java

// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
AgeSignalsManager ageSignalsManager = AgeSignalsManagerFactory.create(getApplicationContext());

// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
AgeSignalsAccessRequest accessRequest = AgeSignalsAccessRequest.builder()
    .setActivity(this)
    .build();

ageSignalsManager.requestAgeSignalsAccess(accessRequest)
    .addOnSuccessListener(accessResult -> {
        Integer status = accessResult.ageSignalsStatus();
        if (status == AgeSignalsStatus.SHARED) {
            // The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
            // Retrieve the actual age signals.
            retrieveAgeSignals(ageSignalsManager);
        } else {
            // Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
        }
    })
    .addOnFailureListener(exception -> {
        // Handle API/Play Store connection and system errors
    });

private void retrieveAgeSignals(AgeSignalsManager manager) {
    // 3. Perform the actual age signals query once sharing is active.
    manager.checkAgeSignals(AgeSignalsRequest.builder().build())
        .addOnSuccessListener(ageSignalsResult -> {
            String installId = ageSignalsResult.installId();
            Integer ageLower = ageSignalsResult.ageLower();
            Integer ageUpper = ageSignalsResult.ageUpper();
            Date significantChangeDate = ageSignalsResult.significantChangeApprovalDate();
            @AgeRangeSource Integer ageRangeSource = ageSignalsResult.ageRangeSource();

            if (ageLower != null) {
                if (ageUpper != null) {
                    // The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
                } else {
                    // The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
                }
            } else {
                // Both bounds are null: The user is not sharing their age (e.g. they are a verified adult)
            }
        })
        .addOnFailureListener(exception -> {
            handleAgeSignalsError(exception);
        });
}

ประเด็นสำคัญเกี่ยวกับโค้ด

  • requestAgeSignalsAccess(Activity) วิธีนี้จะตรวจสอบการบล็อกของ สัญญาณอายุปัจจุบันของผู้ใช้และสถานะการแชร์สัญญาณอายุ
  • หลังจากที่คุณเรียกใช้ requestAgeSignalsAccess(Activity) แล้ว Play จะแสดงข้อความแจ้งในแอปในตัว เฉพาะสำหรับผู้ใช้ที่ไม่มีการควบคุมดูแล ผู้ปกครองของผู้ใช้ภายใต้การควบคุมดูแล สามารถเลือกแชร์อายุของบุตรหลานได้โดยจัดการการตั้งค่าการแชร์อายุ ในแอป Family Link
  • หากผู้ใช้ปิดหรือปฏิเสธการแชร์อายุ ระบบจะแสดงข้อความแจ้งในแอป 2-3 ครั้งก่อนที่จะระงับข้อความแจ้ง
  • เมธอด checkAgeSignals() จะรับค่าสัญญาณอายุในคำตอบของ API เมธอดนี้จะแสดงผล ageRangeSource, ageUpper, ageLower และ ค่าการเปลี่ยนแปลงที่สำคัญอื่นๆ