استخدام واجهة برمجة التطبيقات 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.
          }
        });

(اختياري) تلقّي فئات عمرية مخصّصة

إنّ الفئات العمرية التلقائية التي تعرضها واجهة برمجة التطبيقات في نطاقات السلطة والمناطق المعنيّة هي من 0 إلى 12 عامًا، ومن 13 إلى 15 عامًا، ومن 16 إلى 17 عامًا، و18 عامًا فأكثر.

بدلاً من ذلك، لتخصيص الفئات العمرية التلقائية وفقًا للحدّ الأدنى للعمر المسموح به في تطبيقك ، يمكنك تقديم هذه الحدود الدنيا للعمر في تطبيقك على صفحة "مؤشرات الفئات العمرية" في Google Play Console.

1. انتقِل إلى صفحة "مؤشرات الفئات العمرية" في Play Console.
2. في علامة التبويب فئات عمرية مخصّصة ، أدخِل ما يصل إلى ثلاثة حدود دنيا للعمر في تطبيقك. يجب ألا يقل الفارق العمري عن سنتَين، ويمكن تغييره مرة واحدة سنويًا.
3. انقر على حفظ.

ستحل الفئات العمرية المعروضة محل الردّ التلقائي من واجهة برمجة التطبيقات. على سبيل المثال:

• إذا ضبطت حدًا أدنى واحدًا للعمر (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 (الإصدار التجريبي) الحقول والقيم التالية. وقد تتغيّر القيم. إذا كنت تريد الحصول على أحدث القيم، اطلب ردًا من واجهة برمجة التطبيقات عند فتح تطبيقك. أنت مسؤول عن تقديم تجارب مناسبة للفئة العمرية باستخدام هذه المؤشرات.

أمثلة على الردود للمستخدمين في البرازيل

في البرازيل، لا يمكن أن تكون قيمة 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).

التعامل مع رموز أخطاء واجهة برمجة التطبيقات

إذا أرسل تطبيقك طلب بيانات من واجهة برمجة التطبيقات إلى Play Age Signals API وتعذّر استدعاء واجهة برمجة التطبيقات، سيتلقّى تطبيقك رمز خطأ. يمكن أن تحدث هذه الأخطاء لأسباب مختلفة، مثل أنّ تطبيق "متجر Google Play" قديم.

استراتيجية إعادة المحاولة

في الحالات التي يكون فيها المستخدم في جلسة، ننصحك بتنفيذ استراتيجية إعادة محاولة مع حدّ أقصى لعدد المحاولات كشرط للخروج من الاستراتيجية، وذلك لتقليل تأثير الخطأ على تجربة المستخدم قدر الإمكان.