درخواست سیگنال سن

این سند نحوه درخواست سیگنال‌های سنی را با استفاده از API سیگنال‌های سن بازی شرح می‌دهد.

کیت توسعه نرم‌افزار Play Age Signals 0.0.4 یک معماری دو منظوره را معرفی می‌کند که برای ساده‌سازی درخواست‌های سیگنال سن و پشتیبانی از مدل مبتنی بر انتخاب کاربر ما طراحی شده است. برای درخواست سیگنال‌های سن، از این گردش کار سطح بالا استفاده کنید:

متد requestAgeSignalsAccess(Activity) را فراخوانی کنید، که ageSignalsStatus را برمی‌گرداند. مقدار ageSignalsStatus می‌تواند SHARED ، NOT_SHARED یا VERIFICATION_REQUIRED باشد.

  • اگر ageSignalsStatus == NOT_SHARED : برنامه شما سیگنال‌های سن را در پاسخ API دریافت نخواهد کرد.
  • اگر ageSignalsStatus == SHARED : متد checkAgeSignals() را فراخوانی کنید. اگر کاربر یا والد تصمیم به اشتراک‌گذاری سیگنال‌های سن گرفته باشند، شما سیگنال‌های سن را به عنوان بخشی از پاسخ API دریافت می‌کنید و می‌توانید تصمیم بگیرید که چگونه پاسخ را مدیریت کنید.
  • اگر ageSignalsStatus == VERIFICATION_REQUIRED : سن کاربر نامشخص است و کاربر در حوزه قضایی یا منطقه‌ای قرار دارد که تأیید سن و اشتراک‌گذاری سیگنال‌های سن در آن اجباری است. برای دریافت سیگنال سن از گوگل پلی در این مناطق، از کاربر بخواهید برای حل مشکل خود به فروشگاه پلی مراجعه کند.

متد requestAgeSignalsAccess(Activity) بسته به اینکه آیا اشتراک‌گذاری اجباری سن در یک منطقه اعمال می‌شود یا خیر، مقادیر متفاوتی را برمی‌گرداند:

  • برای کاربران واجد شرایط در ایالت‌های آمریکا که قوانین آنها فروشگاه‌های اپلیکیشن را ملزم به ارائه اطلاعات سن تأیید شده به توسعه‌دهندگان می‌کند، پیام درون برنامه‌ای فعال نمی‌شود. در عوض، از کاربران خواسته می‌شود هنگام بازدید از برنامه فروشگاه Play، آن را تأیید یا نظارت را تنظیم کنند. برای تعیین وضعیت تأیید از مقدار ageSignalsStatus استفاده کنید:
  • برای کاربران در مناطق دیگر که اشتراک‌گذاری سن بر اساس انتخاب کاربر یا والدین است:
    • اگر تنظیم کاربر روی «قبل از اشتراک‌گذاری بپرس» باشد، پیام درون‌برنامه‌ای نمایش داده می‌شود. اگر کاربر با اشتراک‌گذاری سن خود موافقت کند، مقدار ageSignalsStatus SHARED است؛ در غیر این صورت، NOT_SHARED .
    • اگر تنظیم کاربر روی Always Share باشد، پیام درون برنامه‌ای نمایش داده نمی‌شود و مقدار ageSignalsStatus SHARED است.
    • اگر تنظیم کاربر روی Never Share باشد، پیام درون برنامه‌ای نمایش داده نمی‌شود و مقدار ageSignalsStatus NOT_SHARED خواهد بود.
    • برای کاربران تحت نظارت، والدین می‌توانند سن فرزند خود را در تنظیمات برنامه Family Link به اشتراک بگذارند. اگر والدین تصمیم به اشتراک‌گذاری سن بگیرند، مقدار ageSignalsStatus SHARED می‌شود، در غیر این صورت NOT_SHARED خواهد بود.

برای درک نحوه‌ی اشتراک‌گذاری سن در گوگل پلی، از جمله تنظیمات مربوط به اعلان درون‌برنامه و اشتراک‌گذاری محدوده‌ی سنی، به اشتراک‌گذاری محدوده‌ی سنی در گوگل پلی مراجعه کنید.

مثال زیر نحوه درخواست سیگنال‌های سن را نشان می‌دهد:

کاتلین

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

جاوا

// 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 و سایر مقادیر تغییر قابل توجه را برمی‌گرداند.