उम्र से जुड़े सिग्नल का अनुरोध करना

इस दस्तावेज़ में, Play Age Signals API का इस्तेमाल करके, उम्र से जुड़े सिग्नल का अनुरोध करने का तरीका बताया गया है.

Play Age Signals 0.0.4 SDK में, दो फ़ंक्शन वाला आर्किटेक्चर शामिल है. इसे उम्र से जुड़े सिग्नल के अनुरोधों को आसान बनाने और उपयोगकर्ता की पसंद के आधार पर बने हमारे मॉडल के साथ काम करने के लिए डिज़ाइन किया गया है. उम्र से जुड़े सिग्नल का अनुरोध करने के लिए, इस हाई-लेवल वर्कफ़्लो का इस्तेमाल करें:

requestAgeSignalsAccess(Activity) तरीके को कॉल करें. इससे ageSignalsStatus मिलता है. ageSignalsStatus की वैल्यू SHARED, NOT_SHARED या VERIFICATION_REQUIRED हो सकती है.

• अगर ageSignalsStatus == NOT_SHARED है, तो आपके ऐप्लिकेशन को एपीआई के रिस्पॉन्स में, उम्र से जुड़े सिग्नल नहीं मिलेंगे.
• अगर ageSignalsStatus == SHARED है, तो checkAgeSignals() तरीके को कॉल करें. अगर उपयोगकर्ता या माता-पिता ने उम्र से जुड़े सिग्नल शेयर करने का फ़ैसला लिया है, तो आपको एपीआई के रिस्पॉन्स के तौर पर, उम्र से जुड़े सिग्नल मिलते हैं. साथ ही, आपके पास यह तय करने का विकल्प होता है कि रिस्पॉन्स को कैसे मैनेज करना है.
• अगर ageSignalsStatus == VERIFICATION_REQUIRED है, तो उपयोगकर्ता की उम्र की जानकारी उपलब्ध नहीं है. साथ ही, उपयोगकर्ता ऐसे अधिकार क्षेत्र या इलाके में है जहां उम्र की पुष्टि से जुड़ी प्रोसेस करना और उम्र से जुड़े सिग्नल शेयर करना ज़रूरी है. इन देशों/इलाकों में Google Play से उम्र का सिग्नल पाने के लिए, उपयोगकर्ता से Play Store पर जाकर अपनी स्थिति ठीक करने के लिए कहें.

requestAgeSignalsAccess(Activity) तरीका, अलग-अलग वैल्यू दिखाता है. यह इस बात पर निर्भर करता है कि किसी देश/इलाके में, उम्र की जानकारी शेयर करना ज़रूरी है या नहीं:

• अमेरिका के उन राज्यों में रहने वाले ऐसे उपयोगकर्ता जो ज़रूरी शर्तें पूरी करते हैं उनके लिए, ऐप्लिकेशन में दिखने वाला प्रॉम्प्ट ट्रिगर नहीं होता. इन राज्यों में ऐसे कानून हैं जिनके तहत, ऐप स्टोर के लिए ज़रूरी है कि वे डेवलपर को, पुष्टि की गई उम्र की जानकारी दें. इसके बजाय, Play Store ऐप्लिकेशन पर जाने पर, उपयोगकर्ताओं से अपनी उम्र की पुष्टि करने या निगरानी की सुविधा सेट अप करने के लिए कहा जाएगा. पुष्टि की स्थिति का पता लगाने के लिए, ageSignalsStatus की वैल्यू का इस्तेमाल करें:
  • अगर उपयोगकर्ता ने उम्र की पुष्टि से जुड़ी प्रोसेस पूरी कर ली है या माता-पिता के कंट्रोल की सुविधा चालू है, तो ageSignalsStatus की वैल्यू SHARED होगी.
  • अगर उपयोगकर्ता ने अब तक अपनी उम्र की पुष्टि नहीं की है या निगरानी की सुविधा सेट अप नहीं की है, तो ageSignalsStatus की वैल्यू VERIFICATION_REQUIRED होगी. ज़्यादा जानकारी के लिए, अमेरिका के जिन राज्यों में उपयोगकर्ताओं के लिए, ऐप स्टोर से जुड़े नए बिल लागू होने जा रहे हैं वहां Google Play में होने वाले बदलाव देखें.
• अन्य देशों/इलाकों में रहने वाले उपयोगकर्ताओं के लिए, उम्र की जानकारी शेयर करने की सुविधा, उपयोगकर्ता या माता-पिता की पसंद पर निर्भर करती है:
  • अगर उपयोगकर्ता की सेटिंग शेयर करने से पहले पूछें है, तो ऐप्लिकेशन में दिखने वाला प्रॉम्प्ट दिखाया जाता है. अगर उपयोगकर्ता अपनी उम्र की जानकारी शेयर करने के लिए सहमत होता है, तो ageSignalsStatus की वैल्यू SHARED होती है. ऐसा न होने पर, NOT_SHARED होती है.
  • अगर उपयोगकर्ता की सेटिंग हमेशा शेयर करें है, तो ऐप्लिकेशन में दिखने वाला प्रॉम्प्ट नहीं दिखाया जाता. साथ ही, ageSignalsStatus की वैल्यू SHARED होती है.
  • अगर उपयोगकर्ता की सेटिंग कभी शेयर न करें है, तो ऐप्लिकेशन में दिखने वाला प्रॉम्प्ट नहीं दिखाया जाता. साथ ही, ageSignalsStatus की वैल्यू NOT_SHARED होती है.
  • निगरानी में रखे गए उपयोगकर्ताओं के लिए, माता-पिता या अभिभावक, Family Link ऐप्लिकेशन की सेटिंग में जाकर, अपने बच्चे की उम्र की जानकारी शेयर करने का विकल्प चुन सकते हैं. अगर माता-पिता या अभिभावक, उम्र की जानकारी शेयर करने का विकल्प चुनते हैं, तो ageSignalsStatus की वैल्यू SHARED होगी. ऐसा न होने पर, यह NOT_SHARED होगी.

यहां दी गई इमेज में, 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 (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() तरीके से, एपीआई के रिस्पॉन्स में, उम्र से जुड़े सिग्नल की वैल्यू मिलती है. इस तरीके से, ageRangeSource, ageUpper, ageLower, और अन्य अहम बदलावों की वैल्यू मिलती हैं.