این سند نحوه درخواست نشانهای سن را بااستفاده از Play Age Signals API شرح میدهد.
کیت توسعه نرمافزار Play Age Signals نسخه 0.0.4 معماری دوتابعی را معرفی میکند که برای سادهسازی درخواستهای نشانگر سن و پشتیبانی از مدل مبتنی بر انتخاب کاربر طراحی شده است. برای درخواست نشانهای سن، از این گردش کار سطح بالا استفاده کنید:
روش 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خواهد بود.
- اگر تنظیم کاربر قبلاز همرسانی سؤال شود باشد، پیامواره درونبرنامه نشان داده میشود. اگر کاربر با همرسانی سن خود موافقت کند، مقدار
برای درک نحوه عملکرد همرسانی سن در Google Play، ازجمله پیامواره درونبرنامه و تنظیمات همرسانی گروه سنی، به همرسانی گروه سنی در Google Play مراجعه کنید.
مثال زیر نحوه درخواست سیگنالهای سن را نشان میدهد:
کاتلین
// 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
}
}
.addOnFailureListener { exception ->
handleAgeSignalsError(exception)
}
}
جاوا
// 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()مقدار نشانهای سن را در پاسخ API دریافت میکند. این روشageRangeSource،ageUpper،ageLower، و مقادیر تغییر مهم دیگر را برمیگرداند.