يوضّح هذا المستند كيفية طلب إشارات العمر باستخدام واجهة برمجة التطبيقات Play Age Signals API.
تقدّم حزمة تطوير البرامج (SDK) للإصدار 0.0.4 من Play Age Signals بنية تتضمّن وظيفتَين مصمَّمة لتبسيط طلبات إشارات العمر وتتوافق مع نموذجنا المستند إلى خيارات المستخدمين. لطلب إشارات العمر، استخدِم سير العمل العام التالي:
استدعِ الطريقة requestAgeSignalsAccess(Activity) التي تعرض ageSignalsStatus. يمكن أن تكون قيمة ageSignalsStatus هي SHARED أو NOT_SHARED أو VERIFICATION_REQUIRED.
- إذا كانت القيمة
ageSignalsStatus == NOT_SHARED: لن يتلقّى تطبيقك مؤشرات العمر في استجابة واجهة برمجة التطبيقات. - إذا كانت القيمة
ageSignalsStatus == SHARED: استدعِ الطريقةcheckAgeSignals(). إذا قرّر المستخدم أو أحد الوالدين مشاركة مؤشرات العمر، ستتلقّى هذه المؤشرات كجزء من الردّ من واجهة برمجة التطبيقات، ويمكنك تحديد كيفية التعامل مع الردّ. - إذا كانت القيمة
ageSignalsStatus == VERIFICATION_REQUIRED: يكون عمر المستخدم غير معروف ويقيم في نطاق سلطة أو منطقة سارية يكون فيها التحقّق من العمر ومشاركة مؤشرات العمر أمرًا إلزاميًا. للحصول على إشارة العمر من Google Play في هذه المناطق، اطلب من المستخدم الانتقال إلى متجر Google Play لحلّ مشكلة حالته.
تعرض طريقة requestAgeSignalsAccess(Activity) قيمًا مختلفة
استنادًا إلى ما إذا كانت مشاركة العمر الإلزامية منطبقة في منطقة معيّنة:
- بالنسبة إلى المستخدمين المؤهّلين في الولايات الأمريكية التي تتضمّن قوانين تلزم متاجر التطبيقات بتقديم معلومات مؤكَّدة حول العمر للمطوّرين، لن يتم تشغيل الطلب داخل التطبيق.
بدلاً من ذلك، سيُطلب من المستخدمين إثبات ملكية الحساب أو إعداد ميزات الإشراف عند زيارة تطبيق "متجر Google Play". استخدِم قيمة
ageSignalsStatusلتحديد حالة إثبات ملكية الحساب:- إذا أكمل المستخدم عملية إثبات العمر أو كانت ميزة الإشراف الأبوي مفعَّلة، ستكون قيمة
ageSignalsStatusهيSHARED. - إذا لم يثبت المستخدم عمره أو لم يفعّل ميزة الإشراف، ستكون قيمة
ageSignalsStatusهيVERIFICATION_REQUIRED. لمزيد من المعلومات، يُرجى الاطّلاع على تغييرات في Google Play لمواكبة قوانين التحقّق من الأعمار في بعض الولايات الأمريكية.
- إذا أكمل المستخدم عملية إثبات العمر أو كانت ميزة الإشراف الأبوي مفعَّلة، ستكون قيمة
- بالنسبة إلى المستخدمين في مناطق أخرى تستند فيها مشاركة العمر إلى اختيار المستخدم أو الوالد:
- إذا كان إعداد المستخدم هو طلب الإذن قبل المشاركة، سيظهر الطلب داخل التطبيق. إذا وافق المستخدم على مشاركة عمره، ستكون قيمة
ageSignalsStatusهيSHARED، وإلا ستكونNOT_SHARED. - إذا كان إعداد المستخدم هو المشاركة دائمًا، لن يظهر الطلب داخل التطبيق، وستكون قيمة
ageSignalsStatusهيSHARED. - إذا كان إعداد المستخدم هو عدم المشاركة مطلقًا، لن يظهر الطلب داخل التطبيق، وستكون قيمة
ageSignalsStatusهيNOT_SHARED. - بالنسبة إلى المستخدمين الخاضعين للإشراف، يمكن للوالدَين اختيار مشاركة عمر الطفل في إعدادات تطبيق Family Link. إذا اختار الوالدان مشاركة العمر، ستكون قيمة
ageSignalsStatusهيSHARED، وإلا ستكونNOT_SHARED.
- إذا كان إعداد المستخدم هو طلب الإذن قبل المشاركة، سيظهر الطلب داخل التطبيق. إذا وافق المستخدم على مشاركة عمره، ستكون قيمة
للتعرّف على طريقة عمل ميزة مشاركة العمر على Google Play، بما في ذلك الطلب الذي يظهر لك داخل التطبيق وإعدادات مشاركة الفئة العمرية، اطّلِع على مقالة مشاركة الفئة العمرية على Google Play.
يوضّح المثال التالي كيفية طلب إشارات العمر:
Kotlin
// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
val ageSignalsManager = AgeSignalsManagerFactory.create(applicationContext)
// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
val accessRequest = AgeSignalsAccessRequest.builder()
.setActivity(this)
.build()
ageSignalsManager.requestAgeSignalsAccess(accessRequest)
.addOnSuccessListener { accessResult ->
if (accessResult.ageSignalsStatus() == AgeSignalsStatus.SHARED) {
// The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
// Retrieve the actual age signals.
retrieveAgeSignals(ageSignalsManager)
} else {
// Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
}
}
.addOnFailureListener { exception ->
// Handle API/Play Store connection and system errors
handleAgeSignalsError(exception)
}
private fun retrieveAgeSignals(manager: AgeSignalsManager) {
// 3. Perform the actual age signals query once sharing is active.
manager.checkAgeSignals(AgeSignalsRequest.builder().build())
.addOnSuccessListener { ageSignalsResult ->
val installId = ageSignalsResult.installId()
val ageLower = ageSignalsResult.ageLower()
val ageUpper = ageSignalsResult.ageUpper()
val significantChangeDate = ageSignalsResult.significantChangeApprovalDate()
val ageRangeSource = ageSignalsResult.ageRangeSource()
if (ageLower != null) {
if (ageUpper != null) {
// The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
} else {
// The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
}
} else {
// Both bounds are null: The user is not sharing their age (e.g. they are a verified adult)
}
}
.addOnFailureListener { exception ->
handleAgeSignalsError(exception)
}
}
Java
// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
AgeSignalsManager ageSignalsManager = AgeSignalsManagerFactory.create(getApplicationContext());
// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
AgeSignalsAccessRequest accessRequest = AgeSignalsAccessRequest.builder()
.setActivity(this)
.build();
ageSignalsManager.requestAgeSignalsAccess(accessRequest)
.addOnSuccessListener(accessResult -> {
Integer status = accessResult.ageSignalsStatus();
if (status == AgeSignalsStatus.SHARED) {
// The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
// Retrieve the actual age signals.
retrieveAgeSignals(ageSignalsManager);
} else {
// Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
}
})
.addOnFailureListener(exception -> {
// Handle API/Play Store connection and system errors
});
private void retrieveAgeSignals(AgeSignalsManager manager) {
// 3. Perform the actual age signals query once sharing is active.
manager.checkAgeSignals(AgeSignalsRequest.builder().build())
.addOnSuccessListener(ageSignalsResult -> {
String installId = ageSignalsResult.installId();
Integer ageLower = ageSignalsResult.ageLower();
Integer ageUpper = ageSignalsResult.ageUpper();
Date significantChangeDate = ageSignalsResult.significantChangeApprovalDate();
@AgeRangeSource Integer ageRangeSource = ageSignalsResult.ageRangeSource();
if (ageLower != null) {
if (ageUpper != null) {
// The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
} else {
// The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
}
} else {
// Both bounds are null: The user is not sharing their age (e.g. they are a verified adult)
}
})
.addOnFailureListener(exception -> {
handleAgeSignalsError(exception);
});
}
نقاط أساسية حول الرمز
- تُجري الطريقة
requestAgeSignalsAccess(Activity)عملية تحقّق من الحظر بشأن إشارات العمر الحالية للمستخدم وحالة مشاركة إشارات العمر. - بعد الاتصال بالرقم
requestAgeSignalsAccess(Activity)، يعرض Play طلبًا مدمجًا داخل التطبيق للمستخدمين غير الخاضعين للإشراف فقط. يمكن لوالدَي المستخدمين الخاضعين للإشراف اختيار مشاركة عمر الطفل من خلال إدارة إعدادات مشاركة العمر في تطبيق Family Link. - إذا رفض المستخدم مشاركة عمره أو تجاهل طلب المشاركة، سيظهر الطلب داخل التطبيق عدة مرات قبل أن يتم إيقافه.
- تحصل الطريقة
checkAgeSignals()على قيمة إشارات العمر في الردّ من واجهة برمجة التطبيقات. تعرض هذه الطريقةageRangeSourceوageUpperوageLowerوقيمًا أخرى للتغييرات المهمة.