درخواست نشان‌های سن

این سند نحوه درخواست نشان‌های سن را بااستفاده از 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 است؛ درغیراین‌صورت، 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، و مقادیر تغییر مهم دیگر را برمی‌گرداند.