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

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

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

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

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

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

  • ההנחיה באפליקציה לא מוצגת למשתמשים שעומדים בדרישות במדינות בארה"ב שבהן החוק מחייב את חנויות האפליקציות לספק למפתחים מידע מאומת על הגיל. במקום זאת, המשתמשים יתבקשו לאמת את הגיל או להגדיר פיקוח כשהם ייכנסו לאפליקציית חנות Play. אפשר להשתמש בערך 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.
  • אם המשתמש יסגור את ההודעה או ידחה את בקשת השיתוף של הגיל, ההודעה באפליקציה תוצג כמה פעמים לפני שהיא תוסתר.
  • השיטה checkAgeSignals() מקבלת את הערך של אותות הגיל בתגובת ה-API. השיטה הזו מחזירה את הערכים ageRangeSource, ageUpper, ageLower וערכים אחרים של שינויים משמעותיים.