يوضّح هذا المستند كيفية طلب إشارات العمر باستخدام واجهة برمجة التطبيقات Play Age Signals.
تقدّم حزمة تطوير البرامج (SDK) الإصدار 0.0.4 من "إشارات العمر في Play" بنية تتضمّن وظيفتَين مصمّمة لتبسيط طلبات إشارات العمر وتوفير الدعم لنموذجنا المستند إلى خيارات المستخدمين. لطلب إشارات العمر، استخدِم سير العمل العام التالي:
استدعِ طريقة requestAgeSignalsAccess(Activity) التي تعرض ageSignalsStatus. يمكن أن تكون قيمة ageSignalsStatus هي SHARED أو NOT_SHARED أو VERIFICATION_REQUIRED.
- إذا كانت القيمة
ageSignalsStatus == NOT_SHARED: لن يتلقّى تطبيقك إشارات العمر في استجابة واجهة برمجة التطبيقات. - إذا كانت القيمة
ageSignalsStatus == SHARED: استدعِ الطريقةcheckAgeSignals(). إذا قرّر المستخدم أو أحد الوالدين مشاركة مؤشرات العمر، ستتلقّى هذه المؤشرات كجزء من استجابة واجهة برمجة التطبيقات، ويمكنك تحديد كيفية التعامل مع الاستجابة. - إذا كانت القيمة
ageSignalsStatus == VERIFICATION_REQUIRED: يكون عمر المستخدم غير معروف ويكون المستخدم في نطاق سلطة أو منطقة سارية حيث يكون التحقّق من العمر ومشاركة إشارات العمر أمرًا إلزاميًا. للحصول على إشارة العمر من Google Play في هذه المناطق، اطلب من المستخدم الانتقال إلى "متجر Play" لحلّ مشكلة حالته.
تعرض طريقة requestAgeSignalsAccess(Activity) قيمًا مختلفة
استنادًا إلى ما إذا كانت مشاركة العمر الإلزامية منطبقة في منطقة معيّنة:
- بالنسبة إلى المستخدمين المؤهّلين في الولايات الأمريكية التي تتضمّن قوانين تلزم متاجر التطبيقات بتزويد المطوّرين بمعلومات مؤكّدة حول أعمار المستخدمين، لن يتم تشغيل الطلب داخل التطبيق.
بدلاً من ذلك، سيُطلب من المستخدمين إثبات العمر أو إعداد ميزات الإشراف عند زيارة تطبيق "متجر Play". استخدِم قيمة
ageSignalsStatusلتحديد حالة إثبات العمر:- إذا أكمل المستخدم عملية إثبات العمر أو كانت ميزة الإشراف الأبوي مفعَّلة، ستكون قيمة
ageSignalsStatusهيSHARED. - إذا لم يثبت المستخدم عمره أو لم يفعّل ميزة الإشراف، ستكون قيمة
ageSignalsStatusهيVERIFICATION_REQUIRED. لمزيد من المعلومات، يُرجى الاطّلاع على تغييرات في Google Play لمواكبة قوانين التحقّق من الأعمار في بعض الولايات الأمريكية.
- إذا أكمل المستخدم عملية إثبات العمر أو كانت ميزة الإشراف الأبوي مفعَّلة، ستكون قيمة
- بالنسبة إلى المستخدمين في المناطق الأخرى التي تستند فيها مشاركة العمر إلى اختيار المستخدم أو الوالد:
- إذا كان إعداد المستخدم هو طلب الإذن قبل المشاركة، سيظهر الطلب داخل التطبيق. إذا وافق المستخدم على مشاركة عمره، ستكون قيمة
ageSignalsStatusهيSHARED، وإلا ستكونNOT_SHARED. - إذا كان إعداد المستخدم هو المشاركة دائمًا، لن يظهر الطلب داخل التطبيق، وستكون قيمة
ageSignalsStatusهيSHARED. - إذا كان إعداد المستخدم هو عدم المشاركة مطلقًا، لن يظهر الطلب داخل التطبيق، وستكون قيمة
ageSignalsStatusهيNOT_SHARED. - بالنسبة إلى المستخدمين الخاضعين للإشراف، يمكن للوالدَين اختيار مشاركة عمر الطفل في إعدادات تطبيق Family Link. إذا اختار الوالدان مشاركة العمر، ستكون قيمة
ageSignalsStatusهيSHARED، وإلا ستكونNOT_SHARED.
- إذا كان إعداد المستخدم هو طلب الإذن قبل المشاركة، سيظهر الطلب داخل التطبيق. إذا وافق المستخدم على مشاركة عمره، ستكون قيمة
تعرض الصورة التالية إعدادات النطاق العمري لميزة طلب الإذن قبل المشاركة في إعدادات 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وقيمًا أخرى للتغييرات المهمة.