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

במאמר הזה מוסבר איך לשלוח בקשות לאותות גיל באמצעות 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.

במאמר שיתוף טווח הגילאים ב-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 (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 וערכים אחרים של שינויים משמעותיים.