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

استخدام واجهة برمجة التطبيقات Play Age Signals API (إصدار تجريبي)

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

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

دمج واجهة Play Age Signals API في تطبيقك

تتوفّر واجهة برمجة التطبيقات Play Age Signals API على الهواتف والهواتف القابلة للطي والأجهزة اللوحية التي تعمل بنظام التشغيل Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات) والإصدارات الأحدث. لدمج واجهة برمجة التطبيقات Play Age Signals API في تطبيقك، أضِف التبعية التالية إلى ملف build.gradle في تطبيقك:

implementation 'com.google.android.play:age-signals:0.0.3'

طلب مؤشرات الفئات العمرية

في ما يلي مثال على تقديم طلب للحصول على إشارات العمر:

Kotlin

// 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.
        }
    }

Java

// 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.

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

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

في حال ضبط حد أدنى واحد للعمر (15 عامًا) في Google Play Console:
- إذا كان عمر الطفل يتراوح بين 0 و14 عامًا، سيتم عرض ageLower = 0 وageUpper = 14.
- إذا كان عمرك 15 عامًا أو أكثر، سيتم عرض ageLower = 15.
في حال تحديد حدّين أدنى للعمر (13 و17 عامًا):
- إذا كان عمر الطفل يتراوح بين 0 و12 عامًا، سيتم عرض ageLower = 0 وageUpper = 12.
- سيتم عرض ageLower = 13 وageUpper = 16 للمستخدمين الذين تتراوح أعمارهم بين 13 و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`	تم التحقق من صحته	أثبتت Google عمر المستخدم باستخدام طريقة معقولة تجاريًا، مثل مستند تعريف هوية صادر عن جهة حكومية أو بطاقة ائتمان أو تقدير العمر من خلال الوجه. إذا كانت قيمة `userStatus` هي `VERIFIED`، يمكنك تجاهل الحقول الأخرى. استخدِم `ageLower` و`ageUpper` لتحديد الفئة العمرية للمستخدم.
	معلن	تم تحديد عمر المستخدم من قِبل المستخدم أو أحد الوالدَين أو الوصي القانوني. استخدِم `ageLower` و`ageUpper` لتحديد الفئة العمرية للمستخدم.
	SUPERVISED	لدى المستخدم حساب Google خاضع للإشراف يديره أحد الوالدَين الذي يحدّد عمره. استخدِم `ageLower` و`ageUpper` لتحديد الفئة العمرية للمستخدم. استخدِم `mostRecentApprovalDate` لتحديد آخر تغيير مهم تمت الموافقة عليه.
	SUPERVISED_APPROVAL_PENDING	لدى المستخدم حساب Google خاضعًا للإشراف، ولم يوافق بعد الوالد المشرف على تغيير واحد أو أكثر من التغييرات المهمة المعلّقة. استخدِم `ageLower` و`ageUpper` لتحديد الفئة العمرية للمستخدم. استخدِم `mostRecentApprovalDate` لتحديد آخر تغيير مهم تمت الموافقة عليه.
	SUPERVISED_APPROVAL_DENIED	لدى المستخدم حساب Google خاضعًا للإشراف، ورفض الوالد المشرف الموافقة على تغيير واحد أو أكثر من التغييرات المهمة. استخدِم `ageLower` و`ageUpper` لتحديد الفئة العمرية للمستخدم. استخدِم `mostRecentApprovalDate` لتحديد آخر تغيير مهم تمت الموافقة عليه.
	UNKNOWN	عمر المستخدم غير معروف وهو يقيم في ولاية قضائية أو منطقة سارية. ينطبق ذلك فقط على الولايات الأمريكية: للحصول على إشارة العمر من Google Play، اطلب من المستخدم الانتقال إلى "متجر Play" لتحديد حالته.
	`null`	إما أنّ المستخدم ليس في الولايات القضائية والمناطق السارية. أو أنّ المستخدم لا يشارك عمره مع التطبيقات.
`ageLower`	من 0 إلى 18	الحدّ الأدنى (شامل) للفئة العمرية للمستخدم الخاضع للإشراف. استخدِم الرمزين `ageLower` و`ageUpper` لتحديد الفئة العمرية للمستخدم.
`ageLower`	`null`	`userStatus` غير معروف أو `null`.
`ageUpper`	من 2 إلى 18	الحدّ الأعلى (شامل) للفئة العمرية للمستخدم الخاضع للإشراف استخدِم الرمزين `ageLower` و`ageUpper` لتحديد الفئة العمرية للمستخدم.
`ageUpper`	`null`	إما أن يكون حساب `userStatus` خاضعًا للإشراف وأن يكون عمر المستخدم الذي أقرّ به أحد الوالدَين أكبر من 18 عامًا. أو أنّ `userStatus` غير معروف أو `null`
`mostRecentApprovalDate`	الطابع الزمني	يمثّل هذا الحقل تاريخ `effective from` لآخر تغيير مهم تمت الموافقة عليه. عند تثبيت تطبيق، يتم استخدام تاريخ آخر تغيير مهم قبل التثبيت.
`mostRecentApprovalDate`	`null`	إما أنّ حساب `userStatus` خاضع للإشراف ولم يتم إرسال أي تغيير مهم. تم تأكيد صحة معلومات أو `userStatus` أو أنّها غير معروفة أو `null`.
`installID`	معرّف أبجدي رقمي من إنشاء Play	معرّف يخصّ عمليات تثبيت التطبيقات التي يجريها المستخدمون تحت الإشراف، ويتم تعيينه من قِبل Google Play، ويُستخدَم لإعلامك بحالات إبطال الموافقة على التطبيق. راجِع المستندات المتعلّقة بإبطال الموافقات على التطبيقات.
`installID`	`null`	`userStatus` تم التحقّق منها أو غير معروفة أو `null`.

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

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

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

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

القيمة العددية لرمز الخطأ	رمز الخطأ	الوصف	قابلة لإعادة المحاولة
-1	API_NOT_AVAILABLE	واجهة Play Age Signals API غير متاحة. قد يكون إصدار تطبيق "متجر Play" المثبَّت على الجهاز قديمًا. الحل المحتمل اطلب من المستخدم تحديث "متجر Play".	نعم
-2	PLAY_STORE_NOT_FOUND	لم يتم العثور على تطبيق "متجر Play" على الجهاز. اطلب من المستخدم تثبيت "متجر Play" أو تفعيله.	نعم
-3	NETWORK_ERROR	لم يتم العثور على أي شبكة متاحة. اطلب من المستخدم التحقّق من توفّر اتصال.	نعم
-4	PLAY_SERVICES_NOT_FOUND	"خدمات Play" غير متاحة أو إصدارها قديم جدًا. اطلب من المستخدم تثبيت "خدمات Play" أو تحديثها أو تفعيلها.	نعم
-5	CANNOT_BIND_TO_SERVICE	تعذّر الربط بالخدمة في "متجر Play". قد يرجع ذلك إلى تثبيت إصدار قديم من "متجر Play" على الجهاز أو إلى امتلاء ذاكرة الجهاز. اطلب من المستخدم تحديث تطبيق "متجر Play". أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.	نعم
-6	PLAY_STORE_VERSION_OUTDATED	يجب تحديث تطبيق "متجر Play". اطلب من المستخدم تحديث تطبيق "متجر Play".	نعم
-7	PLAY_SERVICES_VERSION_OUTDATED	يجب تحديث "خدمات Play". اطلب من المستخدم تحديث "خدمات Play".	نعم
-8	CLIENT_TRANSIENT_ERROR	حدث خطأ عابر في جهاز العميل. تنفيذ استراتيجية إعادة المحاولة مع تحديد الحد الأقصى لعدد المحاولات كشرط للخروج إذا استمرّت المشكلة، اطلب من المستخدم إعادة المحاولة لاحقًا.	نعم
-9	APP_NOT_OWNED	لم يتم تثبيت التطبيق من خلال Google Play. اطلب من المستخدم الحصول على تطبيقك من Google Play.	لا
-10	SDK_VERSION_OUTDATED	لم يعُد إصدار حزمة تطوير البرامج (SDK) الخاصة بميزة "إشارات الفئة العمرية على Play" متاحًا. اطلب من المستخدم تحديث تطبيقك إلى إصدار أحدث يستخدم إصدارًا حديثًا من حزمة تطوير البرامج (SDK) الخاصة بميزة "إشارات الفئة العمرية على Play".	لا
-100	INTERNAL_ERROR	حدث خطأ داخلي غير معروف. تنفيذ استراتيجية إعادة المحاولة مع تحديد الحد الأقصى لعدد المحاولات كشرط للخروج إذا استمرّت المشكلة، اطلب من المستخدم إعادة المحاولة لاحقًا. إذا تعذّر ذلك باستمرار، يُرجى التواصل مع فريق دعم المطوّرين على Google Play وتضمين Play Age Signals API في الموضوع، بالإضافة إلى أكبر قدر ممكن من التفاصيل الفنية (مثل تقرير عن الخطأ).	لا

نظرة عامة

إرسال إشعارات بالتغييرات المهمة