طلب إشارات الفئات العمرية

يوضِّح هذا المستند كيفية طلب إشارات العمر باستخدام واجهة Play Age Signals API.

يقدّم الإصدار 0.0.4 من حزمة تطوير البرامج (SDK) لـ 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، وإلا تكون 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
            }
        }
        .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 وقيم التغيير المهمة الأخرى.