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

يوضّح هذا المستند كيفية طلب إشارات العمر باستخدام واجهة برمجة التطبيقات 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، وإلا ستكون NOT_SHARED.
    • إذا كان إعداد المستخدم هو المشاركة دائمًا، لن يظهر الطلب داخل التطبيق، وستكون قيمة ageSignalsStatus هي SHARED.
    • إذا كان إعداد المستخدم هو عدم المشاركة مطلقًا، لن يظهر الطلب داخل التطبيق، وستكون قيمة ageSignalsStatus هي NOT_SHARED.
    • بالنسبة إلى المستخدمين الخاضعين للإشراف، يمكن للوالدَين اختيار مشاركة عمر الطفل في إعدادات تطبيق Family Link. إذا اختار الوالدان مشاركة العمر، ستكون قيمة ageSignalsStatus هي SHARED، وإلا ستكون NOT_SHARED.

تعرض الصورة التالية إعدادات النطاق العمري لميزة طلب الإذن قبل المشاركة في إعدادات Play.

قائمة إعدادات Google Play تعرض خيارات مشاركة العمر: "طلب الإذن قبل المشاركة" و"المشاركة دائمًا" و"عدم المشاركة"
الشكل 1. يمكنك إدارة إعدادات مشاركة العمر في Play.

تعرض الصورة التالية طلب مشاركة الفئة العمرية داخل التطبيق الذي يظهر للمستخدمين عند طلب العمر من خلال واجهة برمجة التطبيقات وعندما يكون الإعداد السؤال قبل المشاركة مفعّلاً.

مربّع إفادة الموافقة داخل التطبيق يطلب من المستخدم مشاركة فئته العمرية مع التطبيق
الشكل 2. طلب مشاركة الفئة العمرية داخل التطبيق

تعرض الصورة التالية كيف يمكن للمستخدم تفعيل ميزة مشاركة العمر أو إيقافها لتطبيق محدّد.

مربّع حوار الإعدادات لتطبيق معيّن يعرض مفتاح تبديل لتفعيل ميزة مشاركة الفئة العمرية أو إيقافها
الشكل 3. فعِّل ميزة مشاركة العمر أو أوقِفها لتطبيق معيّن.

يوضّح المثال التالي كيفية طلب إشارات العمر:

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 وقيمًا أخرى للتغييرات المهمة.