בקשת אותות גיל

במסמך הזה מוסבר איך לבקש אותות גיל באמצעות Play Age Signals API.

גרסה 0.0.4 של Play Age Signals SDK מציגה ארכיטקטורה עם שתי פונקציות שנועדה לפשט את הבקשות לאותות גיל ולתמוך במודל שלנו שמבוסס על אפשרויות בחירה למשתמשים. כדי לבקש אותות גיל, צריך להשתמש בתהליך העבודה הכללי הבא:

מפעילים את ה-method‏ requestAgeSignalsAccess(Activity), שמחזירה את ageSignalsStatus. הערך של ageSignalsStatus יכול להיות SHARED,‏ NOT_SHARED או VERIFICATION_REQUIRED.

  • אם ageSignalsStatus == NOT_SHARED: האפליקציה לא תקבל אותות גיל בתגובה מה-API.
  • אם ageSignalsStatus == SHARED: מפעילים את ה-method‏ checkAgeSignals(). אם המשתמש או ההורה החליטו לשתף את אותות הגיל, תקבלו אותות גיל כחלק מהתגובה מה-API, ותוכלו להחליט איך לטפל בתגובה.
  • אם ageSignalsStatus == VERIFICATION_REQUIRED: גיל המשתמש לא ידוע והמשתמש נמצא בסמכות שיפוט או באזור רלוונטיים שבהם חובה לאמת את הגיל ולשתף אותות גיל. כדי לקבל אות גיל מ-Google Play באזורים האלה, צריך לבקש מהמשתמש להיכנס לחנות Play כדי לפתור את הבעיה.

ה-method‏ requestAgeSignalsAccess(Activity) מחזירה ערכים שונים בהתאם לאזור שבו חובה לשתף את הגיל:

  • למשתמשים שעומדים בדרישות במדינות בארה"ב שבהן החוקים מחייבים חנויות אפליקציות לספק למפתחים פרטי גיל מאומתים, ההודעה באפליקציה לא מופעלת. במקום זאת, המשתמשים יתבקשו לאמת את הגיל או להגדיר פיקוח כשהם ייכנסו לאפליקציה של חנות Play. אפשר להשתמש בערך של ageSignalsStatus כדי לקבוע את סטטוס האימות:
  • למשתמשים באזורים אחרים שבהם שיתוף הגיל מבוסס על בחירת המשתמש או ההורה:
    • אם המשתמש בחר באפשרות לבקש לפני השיתוף, תוצג לו בקשה בתוך האפליקציה. אם המשתמש מסכים לשתף את הגיל שלו, הערך של ageSignalsStatus הוא SHARED. אחרת, הערך הוא NOT_SHARED.
    • אם ההגדרה של המשתמש היא שיתוף תמיד, ההודעה באפליקציה לא מוצגת והערך של ageSignalsStatus הוא SHARED.
    • אם המשתמש בחר בהגדרה Never Share, ההודעה באפליקציה לא מוצגת והערך של ageSignalsStatus הוא NOT_SHARED.
    • הורים למשתמשים בפיקוח יכולים לבחור אם לשתף את הגיל של הילד או הילדה בהגדרות של אפליקציית Family Link. אם ההורים בוחרים לשתף את הגיל, הערך של ageSignalsStatus יהיה SHARED. אחרת, הוא יהיה NOT_SHARED.

במאמר שיתוף טווח הגילאים ב-Google Play מוסבר איך פועל שיתוף הגיל ב-Google Play, כולל ההודעה שמופיעה באפליקציה והגדרות השיתוף של טווח הגילאים.

בדוגמה הבאה אפשר לראות איך לבקש אותות גיל:

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
            }
        }
        .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);
        });
}

מידע חשוב על הקוד

  • ה-method‏ requestAgeSignalsAccess(Activity) מבצעת בדיקת חסימה של אותות הגיל הנוכחיים של המשתמש ושל סטטוס השיתוף של אותות הגיל.
  • אחרי שקוראים ל-requestAgeSignalsAccess(Activity), מוצגת ב-Play הנחיה מובנית בתוך האפליקציה רק למשתמשים לא מפוקחים. הורים למשתמשים בפיקוח יכולים לבחור אם לשתף את הגיל של הילד או הילדה שלהם באמצעות ניהול הגדרות שיתוף הגיל באפליקציית Family Link.
  • אם המשתמש סוגר את ההודעה או דוחה את שיתוף הגיל, ההודעה באפליקציה תוצג כמה פעמים לפני שהיא תוסתר.
  • השיטה checkAgeSignals() מקבלת את ערך אותות הגיל בתגובה מה-API. השיטה הזו מחזירה את הערכים ageRangeSource,‏ ageUpper,‏ ageLower וערכים אחרים של שינויים משמעותיים.