שימוש ב-Play Age Signals API (בטא)

// Create an instance of a manager
val ageSignalsManager =
    AgeSignalsManagerFactory.create(ApplicationProvider.getApplicationContext())

// Request an age signals check
ageSignalsManager
    .checkAgeSignals(AgeSignalsRequest.builder().build())
    .addOnSuccessListener { ageSignalsResult ->
        // Store the install ID for later...
        val installId = ageSignalsResult.installId()

        if (ageSignalsResult.userStatus() == AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_DENIED) {
          // Disallow access...
        } else {
           // Do something else if the user is VERIFIED, DECLARED, SUPERVISED, etc.
        }
    }

// Create an instance of a manager
AgeSignalsManager ageSignalsManager =
    AgeSignalsManagerFactory.create(ApplicationProvider.getApplicationContext());

// Request an age signals check
ageSignalsManager
    .checkAgeSignals(AgeSignalsRequest.builder().build())
    .addOnSuccessListener(
        ageSignalsResult -> {
          // Store the install ID for later...
          String installId = ageSignalsResult.installId();

          if (ageSignalsResult
              .userStatus()
              .equals(AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_DENIED)) {
            // Disallow access ...
          } else {
            // Do something else if the user is SUPERVISED, VERIFIED, etc.
          }
        });

(אופציונלי) קבלת טווחי גילאים בהתאמה אישית

טווחי הגילאים ש-API מחזיר כברירת מחדל באזורים ובסמכויות שיפוט רלוונטיים הם 0-12, ‏13-15, ‏16-17 ו-18 ומעלה.

לחלופין, כדי להתאים אישית את טווחי הגילאים שמוחזרים כברירת מחדל בהתאם לדרישות הגיל המינימלי באפליקציה, אפשר לציין את הגילאים המינימליים האלה בדף אותות גיל ב-Google Play Console.

1. עוברים לדף אותות גיל ב-Play Console.
2. בכרטיסייה טווחי גילאים בהתאמה אישית, מזינים עד שלושה גילים מינימליים לאפליקציה. הגילים המינימליים צריכים להיות בהפרש של שנתיים לפחות, ואפשר לשנות אותם פעם בשנה.
3. לוחצים על שמירה.

טווחי הגילאים שיוחזרו יחליפו את תגובת ברירת המחדל של ה-API. לדוגמה:

• אם הגדרתם גיל מינימלי אחד (15) ב-Google Play Console:

  • אם הגיל הוא 0 עד 14, הפונקציה תחזיר ageLower = 0 ו-ageUpper = 14.
  • אם הגיל הוא 15 ומעלה, הפונקציה תחזיר ageLower = 15.

• אם מגדירים שני גילים מינימליים (13 ו-17):

  • אם הגיל הוא בין 0 ל-12, הפונקציה תחזיר את הערכים ageLower = 0 ו-ageUpper = 12.
  • אם הגיל הוא 13 עד 16, הפונקציה מחזירה ageLower = 13 ו-ageUpper = 16.
  • אם הגיל הוא 17 ומעלה, הפונקציה תחזיר ageLower = 17.

• אם מגדירים שלושה גילים מינימליים (11, ‏13 ו-15):

  • אם הגיל הוא בין 0 ל-10, הפונקציה תחזיר את הערכים ageLower = 0 ו-ageUpper = 10.
  • אם הגיל הוא 11 או 12, הפונקציה תחזיר ageLower = 11 ו-ageUpper = 12.
  • אם הגיל הוא 13 או 14, הפונקציה תחזיר ageLower = 13 ו-ageUpper = 14.
  • אם הגיל הוא 15 ומעלה, הפונקציה תחזיר ageLower = 15.

תגובות לאותות גיל

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

תשובות לדוגמה למשתמשים בברזיל

בברזיל, הערך של userStatus יכול להיות רק DECLARED, UNKNOWN או null.

אם משתמש הצהיר על הגיל שלו ומשתף אותו עם אפליקציות, תקבלו את הנתונים הבאים:

• הערך של userStatus יהיה AgeSignalsVerificationStatus.DECLARED.
• הערך ageLower יהיה מספר (לדוגמה, 13).
• ‫ageUpper יהיה מספר או null (לדוגמה, 15).
• שדות אחרים בתשובה יהיו null.

אם הגיל של המשתמש לא ידוע, תקבלו את הפרטים הבאים:

• הערך של userStatus יהיה AgeSignalsVerificationStatus.UNKNOWN.
• שדות אחרים בתשובה יהיו null.

אם הגיל של משתמש לא משותף עם אפליקציות, תקבלו את ההודעה הבאה:

• הערך של userStatus יהיה null.
• שדות אחרים בתשובה יהיו null.

סטטוס המשתמש יכול להשתנות ל-DECLARED ברגע שגיל המשתמש זמין לשיתוף.

דוגמאות לתגובות למשתמשים במדינות בארה"ב

במדינות מסוימות בארה"ב, הערך של userStatus יכול להיות VERIFIED,‏ SUPERVISED,‏ SUPERVISED_APPROVAL_PENDING,‏ SUPERVISED_APPROVAL_DENIED,‏ UNKNOWN או null.

אם המשתמש מאומת, תקבלו את הפרטים הבאים:

• הערך של userStatus יהיה AgeSignalsVerificationStatus.VERIFIED.
• הערך ageLower יהיה מספר (למשל, 18).
• ‫ageUpper יהיה מספר או null (לדוגמה, null).
• שדות אחרים בתשובה יהיו null.

משתמש בפיקוח יקבל את ההודעות הבאות:

• הערך של userStatus יהיה AgeSignalsVerificationStatus.SUPERVISED.
• הערך ageLower יהיה מספר (לדוגמה, 13).
• ‫ageUpper יהיה מספר או null (לדוגמה, 15).
• ‫mostRecentApprovalDate יהיה אובייקט תאריך של Java (לדוגמה, 2026-01-01) או null (אם לא אושר שינוי משמעותי).
• installID יהיה מזהה אלפאנומרי שנוצר על ידי Play (לדוגמה, 550e8400-e29b-41d4-a716-446655441111).

אם יש משתמש בפיקוח שהבקשה שלו לאישור שינוי משמעותי נמצאת בהמתנה, תקבלו את ההודעה הבאה:

• userStatus יהיה AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_PENDING.
• הערך ageLower יהיה מספר (לדוגמה, 13).
• ‫ageUpper יהיה מספר או null (לדוגמה, 15).
• ‫mostRecentApprovalDate יהיה אובייקט תאריך של Java (לדוגמה, 2026-01-01) או null (אם לא אושר שינוי משמעותי).
• ‫installID יהיה מזהה אלפאנומרי שנוצר על ידי Play (לדוגמה, 550e8400-e29b-41d4-a716-446655441111).

טיפול בקודי שגיאה של API

אם האפליקציה שולחת בקשת API ל-Play Age Signals API והקריאה נכשלת, האפליקציה מקבלת קוד שגיאה. השגיאות האלה יכולות לקרות בגלל מגוון סיבות, למשל אם האפליקציה של חנות Play לא עדכנית.

אסטרטגיה של ניסיון חוזר

במקרים שבהם המשתמש נמצא בסשן, מומלץ להטמיע אסטרטגיה של ניסיון חוזר עם מספר מקסימלי של ניסיונות כתנאי יציאה, כדי שהשגיאה תשבש את חוויית המשתמש כמה שפחות.