استخدام واجهة برمجة التطبيقات 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. ستحل الفئات العمرية المعروضة محل الردّ التلقائي من واجهة برمجة التطبيقات. على سبيل المثال، إذا حدّدت الحد الأدنى للعمر بـ 9 و15 و17 عامًا، فإنه سيتم تصنيف المستخدم البالغ من العمر 14 عامًا ضمن الفئة العمرية من 10 إلى 15 عامًا.

لتخصيص الفئات العمرية التلقائية التي تعرضها واجهة Age Signals API، يمكنك تقديم الحدّ الأدنى للعمر المسموح به في تطبيقك باتّباع الخطوات التالية:

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

ردود مؤشرات الفئات العمرية

يتضمّن ردّ واجهة Play Age Signals API (الإصدار التجريبي) الحقول والقيم التالية. وقد تتغيّر القيم. إذا كنت تريد الحصول على أحدث القيم، اطلب الحصول على ردّ من واجهة برمجة التطبيقات عند فتح تطبيقك. أنت المسؤول عن توفير تجارب مناسبة للفئة العمرية باستخدام هذه الإشارات.

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

في البرازيل، يمكن أن تكون قيمة userStatus إما DECLARED أو UNKNOWN.

بالنسبة إلى المستخدم الذي أفصح عن عمره، ستتلقّى ما يلي:

• سيصبح userStatus هو AgeSignalsVerificationStatus.DECLARED.
• سيكون ageLower رقمًا (على سبيل المثال، 13).
• سيكون ageUpper رقمًا أو null (على سبيل المثال، 15).
• ستكون حقول الرد الأخرى null.

بالنسبة إلى مستخدم غير معروف العمر، ستتلقّى ما يلي:

• سيصبح userStatus هو AgeSignalsVerificationStatus.UNKNOWN.
• ستكون حقول الرد الأخرى null.

قد تتغيّر حالة المستخدم من UNKNOWN إلى 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 وتعذّر إرسال الطلب، سيتلقّى تطبيقك رمز خطأ. ويمكن أن تحدث هذه الأخطاء لأسباب مختلفة، مثل أن يكون تطبيق "متجر Play" قديمًا.

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

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