रनटाइम अनुमतियों का अनुरोध करें

हर Android ऐप्लिकेशन, सीमित ऐक्सेस वाले सैंडबॉक्स में चलता है. अगर आपके ऐप्लिकेशन को अपने सैंडबॉक्स के बाहर के संसाधनों या जानकारी का इस्तेमाल करना है, तो रनटाइम अनुमति का एलान किया जा सकता है. साथ ही, अनुमति का अनुरोध सेट अप किया जा सकता है, ताकि ऐप्लिकेशन को यह ऐक्सेस मिल सके. ये चरण, अनुमतियों का इस्तेमाल करने के वर्कफ़्लो का हिस्सा हैं.

कोई दूसरा तरीका अपनाएं.

अगर आपने कोई खतरनाक अनुमतियां मांगी हैं और आपका ऐप्लिकेशन Android 6.0 (एपीआई लेवल 23) या उसके बाद के वर्शन वाले डिवाइस पर इंस्टॉल है, तो आपको रनटाइम के दौरान खतरनाक अनुमतियों का अनुरोध करना होगा. इसके लिए, इस गाइड में दिए गए चरणों का पालन करें.

अगर आपने ज़्यादा जोखिम वाली कोई भी अनुमति नहीं मांगी है या आपका ऐप्लिकेशन ऐसे डिवाइस पर इंस्टॉल है जिस पर Android 5.1 (एपीआई लेवल 22) या इससे पहले का वर्शन चल रहा है, तो अनुमतियां अपने-आप मिल जाती हैं. ऐसे में, आपको इस पेज पर दिए गए बाकी चरणों को पूरा करने की ज़रूरत नहीं होती.

सामान्य सिद्धांत

रनटाइम के दौरान अनुमतियों का अनुरोध करने के बुनियादी सिद्धांत यहां दिए गए हैं:

  • जब उपयोगकर्ता उस सुविधा के साथ इंटरैक्ट करना शुरू करे जिसके लिए अनुमति ज़रूरी है, तब कॉन्टेक्स्ट में अनुमति मांगें.
  • उपयोगकर्ता को ब्लॉक न करें. शिक्षा से जुड़े यूज़र इंटरफ़ेस (यूआई) के फ़्लो को रद्द करने का विकल्प हमेशा दें. जैसे, अनुमतियां मांगने की वजह बताने वाला फ़्लो.
  • अगर उपयोगकर्ता किसी सुविधा के लिए ज़रूरी अनुमति को अस्वीकार या निरस्त करता है, तो ऐप्लिकेशन से उस सुविधा के लिए किए जाने वाले अनुरोध को हटा दें, ताकि उपयोगकर्ता ऐप्लिकेशन का इस्तेमाल जारी रख सके. इसके लिए, ऐसी सुविधा को बंद किया जा सकता है जिसके लिए, उपयोगकर्ता की अनुमति की ज़रूरत पड़ती है.
  • सिस्टम के किसी भी व्यवहार के बारे में अनुमान न लगाएं. उदाहरण के लिए, यह न मान लें कि अनुमतियां एक ही अनुमति ग्रुप में दिखती हैं. अनुमति समूह से, सिस्टम को सिर्फ़ यह मदद मिलती है कि जब कोई ऐप्लिकेशन मिलती-जुलती अनुमतियों का अनुरोध करता है, तो सिस्टम डायलॉग की संख्या कम हो जाती है.

अनुमतियों का अनुरोध करने के लिए वर्कफ़्लो

अपने ऐप्लिकेशन में रनटाइम की अनुमतियों का एलान करने और उनका अनुरोध करने से पहले, यह आकलन करें कि क्या आपके ऐप्लिकेशन को ऐसा करने की ज़रूरत है. अपने ऐप्लिकेशन में कई इस्तेमाल के उदाहरणों को पूरा किया जा सकता है. जैसे, फ़ोटो लेना, मीडिया चलाने की सुविधा को रोकना, और काम के विज्ञापन दिखाना. इसके लिए, आपको किसी भी अनुमति का एलान करने की ज़रूरत नहीं है.

अगर आपको लगता है कि आपके ऐप्लिकेशन को रनटाइम की अनुमतियों का एलान करना और उनके लिए अनुरोध करना ज़रूरी है, तो यह तरीका अपनाएं:

  1. अपने ऐप्लिकेशन की मेनिफ़ेस्ट फ़ाइल में, उन अनुमतियों का एलान करें जिनकी ज़रूरत आपके ऐप्लिकेशन को अनुरोध करने के लिए पड़ सकती है.
  2. अपने ऐप्लिकेशन के यूज़र एक्सपीरियंस को इस तरह से डिज़ाइन करें कि ऐप्लिकेशन में की जाने वाली खास कार्रवाइयां, रनटाइम की खास अनुमतियों से जुड़ी हों. उपयोगकर्ताओं को बताएं कि किन कार्रवाइयों के लिए, उन्हें आपके ऐप्लिकेशन को उपयोगकर्ता के निजी डेटा को ऐक्सेस करने की अनुमति देनी पड़ सकती है.
  3. उपयोगकर्ता के टास्क या कार्रवाई शुरू करने का इंतज़ार करें. यह टास्क या कार्रवाई, आपके ऐप्लिकेशन में उपयोगकर्ता के निजी डेटा को ऐक्सेस करने से जुड़ी होनी चाहिए. उस समय, आपका ऐप्लिकेशन उस डेटा को ऐक्सेस करने के लिए, रनटाइम की अनुमति का अनुरोध कर सकता है.

  4. देखें कि उपयोगकर्ता ने आपके ऐप्लिकेशन को रनटाइम की वह अनुमति पहले ही दे दी है या नहीं जिसकी उसे ज़रूरत है. अगर ऐसा होता है, तो आपका ऐप्लिकेशन उपयोगकर्ता के निजी डेटा को ऐक्सेस कर सकता है. अगर ऐसा नहीं है, तो अगले चरण पर जाएं.

    आपको हर बार यह देखना होगा कि आपके पास किसी ऐसे ऑपरेशन को पूरा करने की अनुमति है या नहीं जिसके लिए अनुमति ज़रूरी है.

  5. देखें कि क्या आपके ऐप्लिकेशन को उपयोगकर्ता को यह वजह बतानी चाहिए कि उसे किसी रनटाइम अनुमति की ज़रूरत क्यों है. अगर सिस्टम को लगता है कि आपके ऐप्लिकेशन को वजह नहीं दिखानी चाहिए, तो यूज़र इंटरफ़ेस (यूआई) एलिमेंट दिखाए बिना सीधे अगले चरण पर जाएं.

    अगर सिस्टम को लगता है कि आपके ऐप्लिकेशन को वजह दिखानी चाहिए, तो यूज़र इंटरफ़ेस (यूआई) एलिमेंट में उपयोगकर्ता को वजह दिखाएं. इस वजह में, साफ़ तौर पर बताएं कि आपका ऐप्लिकेशन किस डेटा को ऐक्सेस करने की कोशिश कर रहा है. साथ ही, यह भी बताएं कि अगर उपयोगकर्ता रनटाइम की अनुमति देता है, तो ऐप्लिकेशन उसे क्या फ़ायदे दे सकता है. जब उपयोगकर्ता वजह जान ले, तब अगले चरण पर जाएं.

  6. रनटाइम की अनुमति का अनुरोध करें, जो आपके ऐप्लिकेशन को उपयोगकर्ता के निजी डेटा को ऐक्सेस करने के लिए ज़रूरी है. सिस्टम, रनटाइम के दौरान अनुमति का अनुरोध दिखाता है. जैसे, अनुमति की खास जानकारी देने वाले पेज पर दिखाया गया है.

  7. उपयोगकर्ता के जवाब की जांच करें. देखें कि उसने रनटाइम अनुमति देने या अस्वीकार करने का विकल्प चुना है या नहीं.

  8. अगर उपयोगकर्ता ने आपके ऐप्लिकेशन को अनुमति दी है, तो आपके पास उपयोगकर्ता के निजी डेटा को ऐक्सेस करने का विकल्प होता है. अगर उपयोगकर्ता ने अनुमति नहीं दी है, तो ऐप्लिकेशन के अनुभव को बेहतर बनाएं, ताकि वह उपयोगकर्ता को ऐसी सुविधाएं दे सके जिनके लिए उस जानकारी की ज़रूरत नहीं होती जिसे अनुमति के ज़रिए सुरक्षित किया जाता है.

पहली इमेज में, इस प्रोसेस से जुड़े वर्कफ़्लो और फ़ैसलों के बारे में बताया गया है:

पहली इमेज. Android पर रनटाइम की अनुमतियों का एलान करने और उनके लिए अनुरोध करने का वर्कफ़्लो दिखाने वाला डायग्राम.

यह पता लगाना कि आपके ऐप्लिकेशन को पहले ही अनुमति दी जा चुकी है या नहीं

यह देखने के लिए कि उपयोगकर्ता ने आपके ऐप्लिकेशन को पहले से ही कोई अनुमति दी है या नहीं, उस अनुमति को ContextCompat.checkSelfPermission() तरीके में पास करें. यह तरीका, आपके ऐप्लिकेशन के पास अनुमति है या नहीं, इसके आधार पर PERMISSION_GRANTED या PERMISSION_DENIED दिखाता है.

बताएं कि आपके ऐप्लिकेशन को इस अनुमति की ज़रूरत क्यों है

जब कॉल किया जाता है, तब सिस्टम की ओर से दिखाया गया अनुमतियों का डायलॉग, requestPermissions() बताता है कि आपके ऐप्लिकेशन को कौनसी अनुमति चाहिए. हालांकि, यह नहीं बताता कि उसे यह अनुमति क्यों चाहिए. कुछ मामलों में, उपयोगकर्ता को यह जानकारी समझ नहीं आ सकती. requestPermissions() को कॉल करने से पहले, उपयोगकर्ता को यह बताना बेहतर होता है कि आपका ऐप्लिकेशन अनुमतियां क्यों चाहता है.

रिसर्च से पता चला है कि अगर उपयोगकर्ताओं को यह पता हो कि ऐप्लिकेशन को अनुमतियों की ज़रूरत क्यों है, तो वे अनुमति के अनुरोधों को आसानी से स्वीकार कर लेते हैं. जैसे, क्या अनुमति ऐप्लिकेशन की किसी मुख्य सुविधा को सपोर्ट करने के लिए ज़रूरी है या विज्ञापन दिखाने के लिए. इसलिए, अगर आपको किसी अनुमति वाले ग्रुप के तहत आने वाले एपीआई कॉल का सिर्फ़ कुछ हिस्सा इस्तेमाल करना है, तो साफ़ तौर पर बताएं कि आपको कौनसी अनुमतियां इस्तेमाल करनी हैं और क्यों. उदाहरण के लिए, अगर सिर्फ़ अनुमानित जगह की जानकारी का इस्तेमाल किया जा रहा है, तो ऐप्लिकेशन के ब्यौरे में या ऐप्लिकेशन के बारे में सहायता लेखों में, लोगों को इसकी जानकारी दें.

कुछ मामलों में, उपयोगकर्ताओं को रीयल टाइम में संवेदनशील डेटा के ऐक्सेस के बारे में बताना भी मददगार होता है. उदाहरण के लिए, अगर आपको कैमरे या माइक्रोफ़ोन का ऐक्सेस चाहिए, तो उपयोगकर्ता को इसकी जानकारी देना ज़रूरी है. इसके लिए, अपने ऐप्लिकेशन में सूचना आइकॉन का इस्तेमाल करें. अगर ऐप्लिकेशन बैकग्राउंड में चल रहा है, तो सूचना ट्रे में आइकॉन का इस्तेमाल करें. इससे उपयोगकर्ता को यह नहीं लगेगा कि आप चुपके से डेटा इकट्ठा कर रहे हैं.

अगर आपको अपने ऐप्लिकेशन में किसी सुविधा को काम करने के लिए अनुमति का अनुरोध करना है, लेकिन उपयोगकर्ता को इसकी वजह साफ़ तौर पर नहीं बताई गई है, तो उपयोगकर्ता को यह बताने का कोई तरीका ढूंढें कि आपको सबसे संवेदनशील अनुमतियों की ज़रूरत क्यों है.

अगर ContextCompat.checkSelfPermission() वाला तरीका PERMISSION_DENIED दिखाता है, तो shouldShowRequestPermissionRationale() को कॉल करें. अगर यह तरीका true दिखाता है, तो उपयोगकर्ता को जानकारी देने वाला यूज़र इंटरफ़ेस (यूआई) दिखाएं. इस यूज़र इंटरफ़ेस (यूआई) में, यह बताएं कि उपयोगकर्ता को जिस सुविधा को चालू करना है उसके लिए किसी खास अनुमति की ज़रूरत क्यों है.

इसके अलावा, अगर आपका ऐप्लिकेशन जगह की जानकारी, माइक्रोफ़ोन या कैमरे से जुड़ी अनुमति का अनुरोध करता है, तो बताएं कि आपके ऐप्लिकेशन को इस जानकारी का ऐक्सेस क्यों चाहिए.

अनुमतियों का अनुरोध करना

जब उपयोगकर्ता को शिक्षा से जुड़ा यूज़र इंटरफ़ेस (यूआई) दिख जाए या shouldShowRequestPermissionRationale() की रिटर्न वैल्यू से पता चले कि आपको शिक्षा से जुड़ा यूज़र इंटरफ़ेस (यूआई) दिखाने की ज़रूरत नहीं है, तब अनुमति का अनुरोध करें. उपयोगकर्ताओं को सिस्टम की अनुमति वाला डायलॉग दिखता है. इसमें वे यह चुन सकते हैं कि आपके ऐप्लिकेशन को कोई खास अनुमति देनी है या नहीं.

इसके लिए, AndroidX लाइब्रेरी में शामिल RequestPermission अनुबंध का इस्तेमाल करें. इसमें, सिस्टम को अनुमति अनुरोध कोड मैनेज करने की अनुमति दें. RequestPermission अनुबंध का इस्तेमाल करने से, लॉजिक को समझना आसान हो जाता है. इसलिए, जब भी हो सके, इस विकल्प का इस्तेमाल करने का सुझाव दिया जाता है. हालांकि, अगर ज़रूरत हो, तो अनुमति के अनुरोध के हिस्से के तौर पर, अनुरोध कोड को खुद मैनेज किया जा सकता है. साथ ही, इस अनुरोध कोड को अनुमति के लिए इस्तेमाल किए जाने वाले कॉलबैक लॉजिक में शामिल किया जा सकता है.

सिस्टम को अनुमति के अनुरोध वाले कोड को मैनेज करने की अनुमति दें

सिस्टम को अनुमति के अनुरोध से जुड़े अनुरोध कोड को मैनेज करने की अनुमति देने के लिए, अपने मॉड्यूल की build.gradle फ़ाइल में इन लाइब्रेरी की डिपेंडेंसी जोड़ें:

  • androidx.activity, वर्शन 1.2.0 या इसके बाद का वर्शन
  • androidx.fragment, 1.3.0 या इसके बाद का वर्शन

इसके बाद, इनमें से किसी एक क्लास का इस्तेमाल किया जा सकता है:

  • किसी एक अनुमति का अनुरोध करने के लिए, RequestPermission का इस्तेमाल करें.
  • एक साथ कई अनुमतियों का अनुरोध करने के लिए, RequestMultiplePermissions का इस्तेमाल करें.

यहां RequestPermission अनुबंध का इस्तेमाल करने का तरीका बताया गया है. RequestMultiplePermissions अनुबंध के लिए भी प्रोसेस लगभग एक जैसी ही होती है.

  1. अपनी गतिविधि या फ़्रैगमेंट के शुरू होने के लॉजिक में, ActivityResultCallback के लागू होने की जानकारी को registerForActivityResult() को किए गए कॉल में पास करें. ActivityResultCallback से यह तय होता है कि अनुमति के अनुरोध पर उपयोगकर्ता के जवाब को आपका ऐप्लिकेशन कैसे हैंडल करेगा.

    registerForActivityResult() की रिटर्न वैल्यू का रेफ़रंस रखें. यह ActivityResultLauncher टाइप की होती है.

  2. ज़रूरत पड़ने पर, सिस्टम की अनुमतियों वाला डायलॉग बॉक्स दिखाने के लिए, ActivityResultLauncher के उस इंस्टेंस पर launch() तरीके को कॉल करें जिसे आपने पिछले चरण में सेव किया था.

    launch() को कॉल करने के बाद, सिस्टम की अनुमतियों वाला डायलॉग बॉक्स दिखता है. जब उपयोगकर्ता कोई विकल्प चुनता है, तो सिस्टम ActivityResultCallback को लागू करने के लिए एसिंक्रोनस तरीके से कॉल करता है. इसे आपने पिछले चरण में तय किया था.

    ध्यान दें: आपका ऐप्लिकेशन, launch() को कॉल करने पर दिखने वाले डायलॉग को कस्टमाइज़ नहीं कर सकता. उपयोगकर्ता को ज़्यादा जानकारी या कॉन्टेक्स्ट देने के लिए, अपने ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) में बदलाव करें. इससे उपयोगकर्ताओं को यह समझने में आसानी होगी कि आपके ऐप्लिकेशन की किसी सुविधा को किसी खास अनुमति की ज़रूरत क्यों है. उदाहरण के लिए, सुविधा चालू करने वाले बटन में मौजूद टेक्स्ट को बदला जा सकता है.

    इसके अलावा, सिस्टम की अनुमति वाले डायलॉग बॉक्स में मौजूद टेक्स्ट में, उस अनुमति ग्रुप का रेफ़रंस होता है जो आपने मांगी है. अनुमतियों के इस ग्रुप को सिस्टम के इस्तेमाल को आसान बनाने के लिए डिज़ाइन किया गया है. आपके ऐप्लिकेशन को यह भरोसा नहीं करना चाहिए कि अनुमतियां किसी खास अनुमति ग्रुप के अंदर या बाहर हैं.

यहां दिया गया कोड स्निपेट दिखाता है कि अनुमतियों के जवाब को कैसे मैनेज किया जाता है:

Kotlin

// Register the permissions callback, which handles the user's response to the
// system permissions dialog. Save the return value, an instance of
// ActivityResultLauncher. You can use either a val, as shown in this snippet,
// or a lateinit var in your onAttach() or onCreate() method.
val requestPermissionLauncher =
    registerForActivityResult(RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Permission is granted. Continue the action or workflow in your
            // app.
        } else {
            // Explain to the user that the feature is unavailable because the
            // feature requires a permission that the user has denied. At the
            // same time, respect the user's decision. Don't link to system
            // settings in an effort to convince the user to change their
            // decision.
        }
    }

Java

// Register the permissions callback, which handles the user's response to the
// system permissions dialog. Save the return value, an instance of
// ActivityResultLauncher, as an instance variable.
private ActivityResultLauncher<String> requestPermissionLauncher =
    registerForActivityResult(new RequestPermission(), isGranted -> {
        if (isGranted) {
            // Permission is granted. Continue the action or workflow in your
            // app.
        } else {
            // Explain to the user that the feature is unavailable because the
            // feature requires a permission that the user has denied. At the
            // same time, respect the user's decision. Don't link to system
            // settings in an effort to convince the user to change their
            // decision.
        }
    });

इस कोड स्निपेट में, अनुमति की जांच करने और ज़रूरत पड़ने पर उपयोगकर्ता से अनुमति का अनुरोध करने का सुझाव दिया गया है:

Kotlin

when {
    ContextCompat.checkSelfPermission(
            CONTEXT,
            Manifest.permission.REQUESTED_PERMISSION
            ) == PackageManager.PERMISSION_GRANTED -> {
        // You can use the API that requires the permission.
    }
    ActivityCompat.shouldShowRequestPermissionRationale(
            this, Manifest.permission.REQUESTED_PERMISSION) -> {
        // In an educational UI, explain to the user why your app requires this
        // permission for a specific feature to behave as expected, and what
        // features are disabled if it's declined. In this UI, include a
        // "cancel" or "no thanks" button that lets the user continue
        // using your app without granting the permission.
        showInContextUI(...)
    }
    else -> {
        // You can directly ask for the permission.
        // The registered ActivityResultCallback gets the result of this request.
        requestPermissionLauncher.launch(
                Manifest.permission.REQUESTED_PERMISSION)
    }
}

Java

if (ContextCompat.checkSelfPermission(
        CONTEXT, Manifest.permission.REQUESTED_PERMISSION) ==
        PackageManager.PERMISSION_GRANTED) {
    // You can use the API that requires the permission.
    performAction(...);
} else if (ActivityCompat.shouldShowRequestPermissionRationale(
        this, Manifest.permission.REQUESTED_PERMISSION)) {
    // In an educational UI, explain to the user why your app requires this
    // permission for a specific feature to behave as expected, and what
    // features are disabled if it's declined. In this UI, include a
    // "cancel" or "no thanks" button that lets the user continue
    // using your app without granting the permission.
    showInContextUI(...);
} else {
    // You can directly ask for the permission.
    // The registered ActivityResultCallback gets the result of this request.
    requestPermissionLauncher.launch(
            Manifest.permission.REQUESTED_PERMISSION);
}

अनुमति के अनुरोध वाले कोड को खुद मैनेज करना

सिस्टम को अनुमति के अनुरोध का कोड मैनेज करने की अनुमति देने के बजाय, अनुमति के अनुरोध का कोड खुद मैनेज किया जा सकता है. इसके लिए, requestPermissions() को कॉल करते समय, अनुरोध कोड शामिल करें.

नीचे दिए गए कोड स्निपेट में बताया गया है कि अनुरोध कोड का इस्तेमाल करके, अनुमति का अनुरोध कैसे किया जाता है:

Kotlin

when {
    ContextCompat.checkSelfPermission(
            CONTEXT,
            Manifest.permission.REQUESTED_PERMISSION
            ) == PackageManager.PERMISSION_GRANTED -> {
        // You can use the API that requires the permission.
        performAction(...)
    }
    ActivityCompat.shouldShowRequestPermissionRationale(
            this, Manifest.permission.REQUESTED_PERMISSION) -> {
        // In an educational UI, explain to the user why your app requires this
        // permission for a specific feature to behave as expected, and what
        // features are disabled if it's declined. In this UI, include a
        // "cancel" or "no thanks" button that lets the user continue
        // using your app without granting the permission.
        showInContextUI(...)
    }
    else -> {
        // You can directly ask for the permission.
        requestPermissions(CONTEXT,
                arrayOf(Manifest.permission.REQUESTED_PERMISSION),
                REQUEST_CODE)
    }
}

Java

if (ContextCompat.checkSelfPermission(
        CONTEXT, Manifest.permission.REQUESTED_PERMISSION) ==
        PackageManager.PERMISSION_GRANTED) {
    // You can use the API that requires the permission.
    performAction(...);
} else if (ActivityCompat.shouldShowRequestPermissionRationale(
        this, Manifest.permission.REQUESTED_PERMISSION)) {
    // In an educational UI, explain to the user why your app requires this
    // permission for a specific feature to behave as expected, and what
    // features are disabled if it's declined. In this UI, include a
    // "cancel" or "no thanks" button that lets the user continue
    // using your app without granting the permission.
    showInContextUI(...);
} else {
    // You can directly ask for the permission.
    requestPermissions(CONTEXT,
            new String[] { Manifest.permission.REQUESTED_PERMISSION },
            REQUEST_CODE);
}

जब उपयोगकर्ता, सिस्टम की अनुमतियों वाले डायलॉग बॉक्स का जवाब दे देता है, तब सिस्टम, onRequestPermissionsResult() को लागू करने के लिए आपके ऐप्लिकेशन को कॉल करता है. सिस्टम, अनुमति के डायलॉग में उपयोगकर्ता के जवाब के साथ-साथ आपके तय किए गए अनुरोध कोड को भी पास करता है. इसे यहां दिए गए कोड स्निपेट में दिखाया गया है:

Kotlin

override fun onRequestPermissionsResult(requestCode: Int,
        permissions: Array<String>, grantResults: IntArray) {
    when (requestCode) {
        PERMISSION_REQUEST_CODE -> {
            // If request is cancelled, the result arrays are empty.
            if ((grantResults.isNotEmpty() &&
                    grantResults[0] == PackageManager.PERMISSION_GRANTED)) {
                // Permission is granted. Continue the action or workflow
                // in your app.
            } else {
                // Explain to the user that the feature is unavailable because
                // the feature requires a permission that the user has denied.
                // At the same time, respect the user's decision. Don't link to
                // system settings in an effort to convince the user to change
                // their decision.
            }
            return
        }

        // Add other 'when' lines to check for other
        // permissions this app might request.
        else -> {
            // Ignore all other requests.
        }
    }
}

Java

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions,
        int[] grantResults) {
    switch (requestCode) {
        case PERMISSION_REQUEST_CODE:
            // If request is cancelled, the result arrays are empty.
            if (grantResults.length > 0 &&
                    grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                // Permission is granted. Continue the action or workflow
                // in your app.
            }  else {
                // Explain to the user that the feature is unavailable because
                // the feature requires a permission that the user has denied.
                // At the same time, respect the user's decision. Don't link to
                // system settings in an effort to convince the user to change
                // their decision.
            }
            return;
        }
        // Other 'case' lines to check for other
        // permissions this app might request.
    }
}

जगह की जानकारी की अनुमतियों का अनुरोध करना

जगह की जानकारी की अनुमतियों का अनुरोध करते समय, रनटाइम अनुमति के लिए अपनाए जाने वाले सबसे सही तरीकों का पालन करें. जगह की जानकारी की अनुमतियों के मामले में एक अहम अंतर यह है कि सिस्टम में, जगह की जानकारी से जुड़ी कई अनुमतियां शामिल होती हैं. आपके ऐप्लिकेशन के इस्तेमाल के उदाहरण के लिए, जगह की जानकारी से जुड़ी ज़रूरी शर्तों के आधार पर यह तय होता है कि आपको कौनसी अनुमतियां चाहिए और उन्हें पाने का तरीका क्या है.

फ़ोरग्राउंड लोकेशन

अगर आपके ऐप्लिकेशन में ऐसी सुविधा है जो सिर्फ़ एक बार या तय समय के लिए जगह की जानकारी शेयर या हासिल करती है, तो उस सुविधा के लिए फ़ोरग्राउंड में जगह की जानकारी ऐक्सेस करने की अनुमति ज़रूरी है. यहां कुछ उदाहरण दिए गए हैं:

  • नेविगेशन ऐप्लिकेशन में, एक सुविधा होती है. इसकी मदद से, उपयोगकर्ताओं को मोड़-दर-मोड़ निर्देश मिलते हैं.
  • मैसेजिंग ऐप्लिकेशन में, एक सुविधा होती है. इसकी मदद से उपयोगकर्ता, अपनी मौजूदा जगह की जानकारी किसी दूसरे उपयोगकर्ता के साथ शेयर कर सकते हैं.

सिस्टम आपके ऐप्लिकेशन को फ़ोरग्राउंड में जगह की जानकारी का इस्तेमाल करने वाला ऐप्लिकेशन मानता है. ऐसा तब होता है, जब आपके ऐप्लिकेशन की कोई सुविधा, डिवाइस की मौजूदा जगह की जानकारी को इनमें से किसी एक स्थिति में ऐक्सेस करती है:

  • आपके ऐप्लिकेशन से जुड़ी कोई गतिविधि दिख रही हो.

  • आपका ऐप्लिकेशन, फ़ोरग्राउंड सेवा चला रहा हो. जब कोई फ़ोरग्राउंड सेवा चल रही होती है, तो सिस्टम उपयोगकर्ता को इसकी जानकारी देता है. इसके लिए, वह एक सूचना दिखाता है. जब ऐप्लिकेशन को बैकग्राउंड में रखा जाता है, तब भी उसके पास ऐक्सेस बना रहता है. जैसे, जब उपयोगकर्ता अपने डिवाइस पर होम बटन दबाता है या डिवाइस का डिसप्ले बंद कर देता है.

    Android 10 (एपीआई लेवल 29) और इसके बाद के वर्शन पर, आपको location का फ़ोरग्राउंड सेवा टाइप घोषित करना होगा. इसके लिए, नीचे दिया गया कोड स्निपेट देखें. Android के पुराने वर्शन पर, हमारा सुझाव है कि आप फ़ोरग्राउंड सेवा के इस टाइप का एलान करें.

    <!-- Recommended for Android 9 (API level 28) and lower. -->
<!-- Required for Android 10 (API level 29) and higher. -->
<service
    android:name="MyNavigationService"
    android:foregroundServiceType="location" ... >
    <!-- Any inner elements go here. -->
</service>

जब आपका ऐप्लिकेशन, यहां दिए गए स्निपेट में दिखाए गए तरीके से, ACCESS_COARSE_LOCATION या ACCESS_FINE_LOCATION अनुमति का अनुरोध करता है, तब आपको फ़ोरग्राउंड में जगह की जानकारी ऐक्सेस करने की अनुमति की ज़रूरत के बारे में बताना होता है:

<manifest ... >
  <!-- Include this permission any time your app needs location information. -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

बैकग्राउंड में लोकेशन ऐक्सेस करना

किसी ऐप्लिकेशन को बैकग्राउंड में जगह की जानकारी ऐक्सेस करने की ज़रूरत तब होती है, जब ऐप्लिकेशन में मौजूद कोई सुविधा, लगातार अन्य उपयोगकर्ताओं के साथ जगह की जानकारी शेयर करती है या जियोफ़ेंसिंग एपीआई का इस्तेमाल करती है. इसके कई उदाहरणों में ये शामिल हैं:

  • जगह की जानकारी शेयर करने वाले किसी ऐप्लिकेशन में, एक ऐसी सुविधा होती है जिसकी मदद से लोग, परिवार के सदस्यों के साथ लगातार जगह की जानकारी शेयर कर सकते हैं.
  • किसी IoT ऐप्लिकेशन में, एक सुविधा होती है. इसकी मदद से उपयोगकर्ता, अपने होम डिवाइसों को इस तरह कॉन्फ़िगर कर सकते हैं कि घर से बाहर जाने पर वे बंद हो जाएं और घर वापस आने पर अपने-आप चालू हो जाएं.

अगर आपका ऐप्लिकेशन, फ़ोरग्राउंड में जगह की जानकारी सेक्शन में बताई गई स्थितियों के अलावा किसी अन्य स्थिति में डिवाइस की मौजूदा जगह की जानकारी ऐक्सेस करता है, तो सिस्टम यह मानता है कि आपका ऐप्लिकेशन बैकग्राउंड में जगह की जानकारी का इस्तेमाल कर रहा है. बैकग्राउंड में जगह की सटीक जानकारी, फ़ोरग्राउंड में जगह की सटीक जानकारी के बराबर होती है. यह इस बात पर निर्भर करती है कि आपका ऐप्लिकेशन, जगह की जानकारी ऐक्सेस करने की कौनसी अनुमतियों का एलान करता है.

Android 10 (एपीआई लेवल 29) और इसके बाद के वर्शन पर, आपको अपने ऐप्लिकेशन के मेनिफ़ेस्ट में ACCESS_BACKGROUND_LOCATION अनुमति के बारे में बताना होगा. इससे, रनटाइम के दौरान बैकग्राउंड में जगह की जानकारी ऐक्सेस करने का अनुरोध किया जा सकेगा. Android के पुराने वर्शन पर, जब आपके ऐप्लिकेशन को फ़ोरग्राउंड में जगह की जानकारी ऐक्सेस करने की अनुमति मिलती है, तो उसे बैकग्राउंड में जगह की जानकारी ऐक्सेस करने की अनुमति भी अपने-आप मिल जाती है.

<manifest ... >
  <!-- Required only when requesting background location access on
       Android 10 (API level 29) and higher. -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>

अनुमति न मिलने की समस्या हल करना

अगर उपयोगकर्ता अनुमति के अनुरोध को अस्वीकार करता है, तो आपके ऐप्लिकेशन को उपयोगकर्ताओं को यह बताना चाहिए कि अनुमति अस्वीकार करने से क्या होगा. खास तौर पर, आपके ऐप्लिकेशन को लोगों को उन सुविधाओं के बारे में बताना चाहिए जो अनुमति न होने की वजह से काम नहीं करती हैं. ऐसा करते समय, इन सबसे सही तरीकों को ध्यान में रखें:

  • उपयोगकर्ता का ध्यान खींचना. अपने ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) के किसी ऐसे हिस्से को हाइलाइट करें जहां ज़रूरी अनुमति न होने की वजह से, सीमित सुविधाएं उपलब्ध हैं. यहां कुछ उदाहरण दिए गए हैं:

    • उस जगह पर एक मैसेज दिखाएं जहां सुविधा के नतीजे या डेटा दिखते हैं.
    • एक ऐसा बटन दिखाएं जिसमें गड़बड़ी का आइकॉन और रंग मौजूद हो.

  • सटीक जानकारी दें. कोई सामान्य मैसेज न दिखाएं. इसके बजाय, यह साफ़ तौर पर बताएं कि ज़रूरी अनुमति न होने की वजह से, आपके ऐप्लिकेशन में कौनसी सुविधाएं उपलब्ध नहीं हैं.

  • उपयोगकर्ता इंटरफ़ेस को ब्लॉक न करें. दूसरे शब्दों में कहें, तो उपयोगकर्ताओं को पूरी स्क्रीन पर चेतावनी वाला ऐसा मैसेज न दिखाएं जिससे वे आपके ऐप्लिकेशन का इस्तेमाल न कर पाएं.

साथ ही, आपके ऐप्लिकेशन को उपयोगकर्ता के उस फ़ैसले का सम्मान करना चाहिए जिसमें उसने अनुमति देने से इनकार किया है. Android 11 (एपीआई लेवल 30) से, अगर कोई उपयोगकर्ता किसी डिवाइस पर आपके ऐप्लिकेशन के इंस्टॉल होने के दौरान, किसी अनुमति के लिए एक से ज़्यादा बार अस्वीकार करें पर टैप करता है, तो आपका ऐप्लिकेशन उस अनुमति का फिर से अनुरोध करता है. ऐसे में, उपयोगकर्ता को सिस्टम की अनुमतियों वाला डायलॉग बॉक्स नहीं दिखता. उपयोगकर्ता की कार्रवाई से पता चलता है कि "दोबारा न पूछें." पिछले वर्शन में, जब भी आपका ऐप्लिकेशन किसी अनुमति का अनुरोध करता था, तब उपयोगकर्ताओं को सिस्टम अनुमतियों का डायलॉग दिखता था. ऐसा तब तक होता था, जब तक उन्होंने "दोबारा न पूछें" चेकबॉक्स या विकल्प को पहले से नहीं चुना होता था.

अगर कोई उपयोगकर्ता अनुमति के अनुरोध को एक से ज़्यादा बार खारिज करता है, तो इसे हमेशा के लिए खारिज करना माना जाता है. यह बहुत ज़रूरी है कि उपयोगकर्ताओं से अनुमतियों के लिए सिर्फ़ तब अनुरोध किया जाए, जब उन्हें किसी सुविधा को ऐक्सेस करने की ज़रूरत हो. ऐसा न करने पर, हो सकता है कि आप गलती से अनुमतियों के लिए फिर से अनुरोध न कर पाएं.

कुछ मामलों में, उपयोगकर्ता की ओर से कोई कार्रवाई किए बिना ही अनुमति अपने-आप अस्वीकार हो सकती है. (अनुमति अपने-आप भी मिल सकती है.) ऑटोमैटिक व्यवहार के बारे में कुछ भी मान लेना सही नहीं है. जब भी आपके ऐप्लिकेशन को ऐसी सुविधा ऐक्सेस करनी हो जिसके लिए अनुमति की ज़रूरत होती है, तो यह देख लें कि आपके ऐप्लिकेशन को अब भी वह अनुमति मिली हुई हो.

ऐप्लिकेशन की अनुमतियां मांगते समय, उपयोगकर्ता को बेहतरीन अनुभव देने के लिए, ऐप्लिकेशन की अनुमतियों से जुड़े सबसे सही तरीके भी देखें.

टेस्टिंग और डीबग करने के दौरान, अनुमति न मिलने की स्थिति की जांच करना

यह पता लगाने के लिए कि किसी ऐप्लिकेशन को हमेशा के लिए अनुमतियां अस्वीकार कर दी गई हैं या नहीं (डीबग करने और टेस्टिंग के लिए), इस कमांड का इस्तेमाल करें:

adb shell dumpsys package PACKAGE_NAME

इसमें PACKAGE_NAME उस पैकेज का नाम है जिसकी जांच करनी है.

कमांड के आउटपुट में ऐसे सेक्शन होते हैं:

...
runtime permissions:
  android.permission.POST_NOTIFICATIONS: granted=false, flags=[ USER_SENSITIVE_WHEN_GRANTED|USER_SENSITIVE_WHEN_DENIED]
  android.permission.ACCESS_FINE_LOCATION: granted=false, flags=[ USER_SET|USER_FIXED|USER_SENSITIVE_WHEN_GRANTED|USER_SENSITIVE_WHEN_DENIED]
  android.permission.BLUETOOTH_CONNECT: granted=false, flags=[ USER_SENSITIVE_WHEN_GRANTED|USER_SENSITIVE_WHEN_DENIED]
...

USER_SET से उन अनुमतियों को फ़्लैग किया जाता है जिन्हें उपयोगकर्ता ने एक बार अस्वीकार कर दिया है. अगर किसी अनुमति को दो बार अस्वीकार करें चुनकर हमेशा के लिए अस्वीकार कर दिया जाता है, तो USER_FIXED उसे फ़्लैग कर देता है.

यह पक्का करने के लिए कि टेस्टर को टेस्टिंग के दौरान अनुरोध वाला डायलॉग दिखे, अपने ऐप्लिकेशन को डीबग करने के बाद इन फ़्लैग को रीसेट करें. इसके लिए, इस कमांड का इस्तेमाल करें:

adb shell pm clear-permission-flags PACKAGE_NAME PERMISSION_NAME user-set user-fixed

PERMISSION_NAME उस अनुमति का नाम है जिसे आपको रीसेट करना है.

Android ऐप्लिकेशन की अनुमतियों की पूरी सूची देखने के लिए, अनुमतियों वाले एपीआई के रेफ़रंस पेज पर जाएं.

एक बार के लिए अनुमतियां

&#39;सिर्फ़ इस बार&#39; विकल्प, डायलॉग बॉक्स में मौजूद तीन बटन में से दूसरा बटन है.
दूसरी इमेज. जब कोई ऐप्लिकेशन, एक बार की अनुमति का अनुरोध करता है, तब दिखने वाला सिस्टम डायलॉग.

Android 11 (एपीआई लेवल 30) से, जब भी आपका ऐप्लिकेशन जगह की जानकारी, माइक्रोफ़ोन या कैमरे से जुड़ी अनुमति का अनुरोध करता है, तो उपयोगकर्ता को दिखने वाले अनुमति के डायलॉग में, सिर्फ़ इस बार नाम का विकल्प दिखता है. इसे इमेज 2 में दिखाया गया है. अगर उपयोगकर्ता इस विकल्प को चुनता है, तो आपके ऐप्लिकेशन को कुछ समय के लिए एक बार की अनुमति दी जाती है.

इसके बाद, आपका ऐप्लिकेशन कुछ समय के लिए इस डेटा को ऐक्सेस कर सकता है. यह समय इन बातों पर निर्भर करता है: आपके ऐप्लिकेशन का व्यवहार और उपयोगकर्ता की कार्रवाइयां:

  • जब तक आपके ऐप्लिकेशन की गतिविधि दिखती है, तब तक आपका ऐप्लिकेशन डेटा ऐक्सेस कर सकता है.
  • अगर उपयोगकर्ता आपके ऐप्लिकेशन को बैकग्राउंड में भेजता है, तो आपका ऐप्लिकेशन कुछ समय के लिए डेटा को ऐक्सेस कर सकता है.
  • अगर गतिविधि दिखते समय फ़ोरग्राउंड सेवा लॉन्च की जाती है और उपयोगकर्ता आपके ऐप्लिकेशन को बैकग्राउंड में ले जाता है, तो फ़ोरग्राउंड सेवा बंद होने तक आपका ऐप्लिकेशन डेटा को ऐक्सेस कर सकता है.

अनुमति रद्द होने पर, ऐप्लिकेशन की प्रोसेस बंद हो जाती है

अगर उपयोगकर्ता, सिस्टम सेटिंग में जाकर एक बार की अनुमति को रद्द कर देता है, तो आपका ऐप्लिकेशन डेटा ऐक्सेस नहीं कर पाएगा. भले ही, आपने फ़ोरग्राउंड सेवा लॉन्च की हो. किसी भी अनुमति की तरह, अगर उपयोगकर्ता आपके ऐप्लिकेशन को दी गई एक बार की अनुमति को रद्द कर देता है, तो आपके ऐप्लिकेशन की प्रोसेस बंद हो जाती है.

जब उपयोगकर्ता अगली बार आपका ऐप्लिकेशन खोलता है और ऐप्लिकेशन की कोई सुविधा, जगह की जानकारी, माइक्रोफ़ोन या कैमरे का ऐक्सेस मांगती है, तो उपयोगकर्ता को फिर से अनुमति देने के लिए कहा जाता है.

इस्तेमाल न की गई अनुमतियां रीसेट करना

Android, इस्तेमाल नहीं की गई रनटाइम अनुमतियों को उनकी डिफ़ॉल्ट स्थिति में रीसेट करने के कई तरीके उपलब्ध कराता है. डिफ़ॉल्ट स्थिति का मतलब है कि अनुमति नहीं दी गई है:

ऐप्लिकेशन का ऐक्सेस हटाना

Android 13 (एपीआई लेवल 33) और इसके बाद के वर्शन पर, आपके पास अपने ऐप्लिकेशन के लिए रनटाइम अनुमतियों का ऐक्सेस हटाने का विकल्प होता है. ये वे अनुमतियां होती हैं जिनकी अब आपके ऐप्लिकेशन को ज़रूरत नहीं है. अपने ऐप्लिकेशन को अपडेट करते समय, यह तरीका अपनाएं. इससे लोगों को यह समझने में आसानी होगी कि आपका ऐप्लिकेशन अब भी कुछ अनुमतियों का अनुरोध क्यों कर रहा है. इस जानकारी से, लोगों का आपके ऐप्लिकेशन पर भरोसा बढ़ता है.

किसी रनटाइम अनुमति का ऐक्सेस हटाने के लिए, उस अनुमति का नाम revokeSelfPermissionOnKill() में पास करें. एक साथ कई रनटाइम अनुमतियों का ऐक्सेस हटाने के लिए, अनुमतियों के नाम का कलेक्शन revokeSelfPermissionsOnKill() में पास करें. अनुमति हटाने की प्रोसेस एसिंक्रोनस तरीके से होती है. साथ ही, यह आपके ऐप्लिकेशन के यूआईडी से जुड़ी सभी प्रोसेस को बंद कर देती है.

सिस्टम को आपके ऐप्लिकेशन के लिए अनुमतियों का ऐक्सेस हटाने के लिए, आपके ऐप्लिकेशन से जुड़ी सभी प्रोसेस बंद करनी होंगी. एपीआई को कॉल करने पर, सिस्टम यह तय करता है कि इन प्रोसेस को कब बंद करना सुरक्षित है. आम तौर पर, सिस्टम तब तक इंतज़ार करता है, जब तक आपका ऐप्लिकेशन फ़ोरग्राउंड के बजाय बैकग्राउंड में लंबे समय तक न चल जाए.

उपयोगकर्ता को यह बताने के लिए कि आपके ऐप्लिकेशन को अब रनटाइम की कुछ अनुमतियों का ऐक्सेस नहीं चाहिए, अगली बार जब उपयोगकर्ता आपका ऐप्लिकेशन लॉन्च करे, तो उसे एक डायलॉग दिखाएं. इस डायलॉग में, अनुमतियों की सूची शामिल की जा सकती है.

इस्तेमाल नहीं किए जा रहे ऐप्लिकेशन की अनुमतियां अपने-आप रीसेट होने की सुविधा

अगर आपका ऐप्लिकेशन, Android 11 (एपीआई लेवल 30) या उसके बाद के वर्शन को टारगेट करता है और कुछ महीनों से इसका इस्तेमाल नहीं किया गया है, तो सिस्टम उपयोगकर्ता के डेटा की सुरक्षा करता है. इसके लिए, वह रनटाइम के दौरान दी गई उन संवेदनशील अनुमतियों को अपने-आप रीसेट कर देता है जो उपयोगकर्ता ने आपके ऐप्लिकेशन को दी थीं. ऐप्लिकेशन को स्लीप मोड में रखने के बारे में ज़्यादा जानने के लिए, गाइड पढ़ें.

अगर ज़रूरी हो, तो डिफ़ॉल्ट हैंडलर बनने का अनुरोध करें

कुछ ऐप्लिकेशन, कॉल लॉग और मैसेज (एसएमएस) से जुड़ी संवेदनशील जानकारी ऐक्सेस करने पर निर्भर होते हैं. अगर आपको कॉल लॉग और एसएमएस मैसेज से जुड़ी अनुमतियों का अनुरोध करना है और अपने ऐप्लिकेशन को Play Store पर पब्लिश करना है, तो आपको उपयोगकर्ता को यह सूचना देनी होगी कि वह आपके ऐप्लिकेशन को सिस्टम के मुख्य फ़ंक्शन के लिए डिफ़ॉल्ट हैंडलर के तौर पर सेट करे. ऐसा, रनटाइम की इन अनुमतियों का अनुरोध करने से पहले करना होगा.

डिफ़ॉल्ट हैंडलर के बारे में ज़्यादा जानकारी पाने के लिए, सिर्फ़ डिफ़ॉल्ट हैंडलर में इस्तेमाल की जाने वाली अनुमतियों के बारे में गाइड देखें. इसमें उपयोगकर्ताओं को डिफ़ॉल्ट हैंडलर का प्रॉम्प्ट दिखाने के बारे में दिशा-निर्देश भी शामिल हैं.

जांच के लिए, रनटाइम की सभी अनुमतियां देना

किसी एम्युलेटर या टेस्ट डिवाइस पर ऐप्लिकेशन इंस्टॉल करते समय, सभी रनटाइम अनुमतियां अपने-आप देने के लिए, adb shell install कमांड के लिए -g विकल्प का इस्तेमाल करें. इसे यहां दिए गए कोड स्निपेट में दिखाया गया है:

adb shell install -g PATH_TO_APK_FILE

अन्य संसाधन

अनुमतियों के बारे में ज़्यादा जानने के लिए, ये लेख पढ़ें:

अनुमतियों का अनुरोध करने के बारे में ज़्यादा जानने के लिए, अनुमतियों के सैंपल देखें

निजता से जुड़े सबसे सही तरीकों के बारे में बताने वाले इस कोडलैब को भी पूरा किया जा सकता है.

पीछे जाएं
ऐप्लिकेशन अनुमतियों का एलान करना
आगे बढ़ें
विशेष अनुमतियों का अनुरोध करें