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

يخزِّن Google Play إشارات العمر على الجهاز لكل مستخدم. عندما ينتقل مستخدم لديه حساب خاضع للإشراف على Google إلى فئة عمرية جديدة، يحدِّث Google Play تلقائيًا إشارات العمر المخزّنة مؤقتًا لهذا المستخدم خلال مدة تتراوح بين أسبوعَين و8 أسابيع بعد تاريخ ميلاده.

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

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

بدلاً من ذلك، لتخصيص الفئات العمرية وفقًا للحدّ الأدنى للعمر المسموح به في تطبيقك، يمكنك تقديم هذه الفئات في صفحة إشارات العمر في Google Play Console. تعرض واجهة Age Signals API الفئات العمرية المخصّصة. على سبيل المثال، إذا حدّدت الحد الأدنى للعمر بـ 9 و15 و17 عامًا، فإنه سيتم تصنيف المستخدم البالغ من العمر 14 عامًا ضمن الفئة العمرية من 10 إلى 15 عامًا. يجب ألا يقل الفارق العمري عن سنتَين، ويمكن تغييره مرة واحدة سنويًا.

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

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

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

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

أمثلة على الردود

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

• سيصبح userStatus هو AgeSignalsVerificationStatus.VERIFIED.
• ستكون حقول الردود الأخرى فارغة.

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

• ستكون قيمة userStatus هي AgeSignalsVerificationStatus.SUPERVISED.
• سيكون ageLower رقمًا (مثل 13).
• سيكون ageUpper رقمًا (مثل 15).
• سيكون mostRecentApprovalDate كائن تاريخ Java (مثل 2026-01-01) أو فارغًا (في حال عدم الموافقة على أي تغيير مهم).
• سيكون installID معرّفًا أبجديًا رقميًا من إنشاء Play (مثلاً 550e8400-e29b-41d4-a716-446655441111).

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

• ستكون قيمة userStatus هي AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_PENDING.
• سيكون ageLower رقمًا (مثل 13).
• سيكون ageUpper رقمًا (مثل 15).
• سيكون mostRecentApprovalDate كائن تاريخ Java (مثل 2026-01-01) أو فارغًا (في حال عدم الموافقة على أي تغيير مهم).
• سيكون installID معرّفًا أبجديًا رقميًا من إنشاء Play (مثلاً 550e8400-e29b-41d4-a716-446655441111).

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

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

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

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