ब्लूटूथ की अनुमतियां

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

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

आपके ऐप्लिकेशन में जिन अनुमतियों का एलान किया जाता है वे आपके ऐप्लिकेशन के टारगेट SDK वर्शन के हिसाब से तय होते हैं.

Android 12 या उसके बाद के वर्शन को टारगेट करना

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

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

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

अगर आपका ऐप्लिकेशन Android 12 (एपीआई लेवल 31) या उसके बाद के वर्शन को टारगेट करता है, तो अपने ऐप्लिकेशन की मेनिफ़ेस्ट फ़ाइल में इन अनुमतियों के बारे में बताएं:

  1. अगर आपका ऐप्लिकेशन ब्लूटूथ डिवाइसों को खोजता है, जैसे कि बीएलई डिवाइस, तो BLUETOOTH_SCAN की अनुमति का एलान करें.
  2. अगर आपका ऐप्लिकेशन मौजूदा डिवाइस को अन्य ब्लूटूथ डिवाइसों के लिए खोजने लायक बनाता है, तो BLUETOOTH_ADVERTISE अनुमति का एलान करें.
  3. अगर आपका ऐप्लिकेशन पहले से जोड़े गए ब्लूटूथ डिवाइसों से संपर्क करता है, तो BLUETOOTH_CONNECT अनुमति का एलान करें.
  4. ब्लूटूथ से जुड़ी अनुमतियों के लेगसी एलान के लिए, android:maxSdkVersion को 30 पर सेट करें. साथ काम करने से जुड़े इस चरण की मदद से, सिस्टम आपके ऐप्लिकेशन को सिर्फ़ ब्लूटूथ की वे अनुमतियां दे पाता है जिनकी ज़रूरत उसे Android 12 या उसके बाद के वर्शन वाले डिवाइसों पर इंस्टॉल करने के लिए होती है.
  5. अगर आपका ऐप्लिकेशन, डिवाइस की जगह का पता लगाने के लिए ब्लूटूथ स्कैन के नतीजों का इस्तेमाल करता है, तो ACCESS_FINE_LOCATION को अनुमति दें. इसके अलावा, यह भी दावा किया जा सकता है कि आपका ऐप्लिकेशन, उपयोगकर्ता की जगह की जानकारी का इस्तेमाल नहीं करता.

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

नीचे दिया गया कोड स्निपेट, Android 12 या उसके बाद के वर्शन को टारगेट करने वाले ऐप्लिकेशन में, ब्लूटूथ से जुड़ी अनुमतियों का एलान करने का तरीका दिखाता है:

<manifest>
    <!-- Request legacy Bluetooth permissions on older devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH"
                     android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
                     android:maxSdkVersion="30" />

    <!-- Needed only if your app looks for Bluetooth devices.
         If your app doesn't use Bluetooth scan results to derive physical
         location information, you can
         <a href="#assert-never-for-location">strongly assert that your app
         doesn't derive physical location</a>. -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

    <!-- Needed only if your app makes the device discoverable to Bluetooth
         devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

    <!-- Needed only if your app communicates with already-paired Bluetooth
         devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

    <!-- Needed only if your app uses Bluetooth scan results to derive physical location. -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    ...
</manifest>

साफ़ तौर पर बताएं कि आपका ऐप्लिकेशन, जगह की जानकारी का इस्तेमाल नहीं करता

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

  1. BLUETOOTH_SCAN की अनुमति के एलान में android:usesPermissionFlags एट्रिब्यूट जोड़ें और इस एट्रिब्यूट की वैल्यू को neverForLocation पर सेट करें.

  2. अगर आपके ऐप्लिकेशन के लिए जगह की जानकारी की ज़रूरत नहीं है, तो अपने ऐप्लिकेशन के मेनिफ़ेस्ट से ACCESS_FINE_LOCATION अनुमति हटा दें.

नीचे दिया गया कोड स्निपेट आपके ऐप्लिकेशन की मेनिफ़ेस्ट फ़ाइल को अपडेट करने का तरीका बताता है:

<manifest>
    <!-- Include "neverForLocation" only if you can strongly assert that
         your app never derives physical location from Bluetooth scan results. -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
                     android:usesPermissionFlags="neverForLocation" />

    <!-- Not needed if you can strongly assert that your app never derives
         physical location from Bluetooth scan results and doesn't need location
         access for any other purpose. -->
    <strike><uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /></strike>
    ...
</manifest>

Android 11 या उससे पहले के वर्शन को टारगेट करना

अगर आपका ऐप्लिकेशन, Android 11 (एपीआई लेवल 30) या इससे पहले के वर्शन को टारगेट करता है, तो अपने ऐप्लिकेशन की मेनिफ़ेस्ट फ़ाइल में इन अनुमतियों के बारे में बताएं:

  • ब्लूटूथ क्लासिक या बीएलई से जुड़ी कोई भी कार्रवाइयां करने के लिए, BLUETOOTH ज़रूरी है. जैसे, कनेक्शन का अनुरोध करना, कनेक्शन स्वीकार करना, और डेटा ट्रांसफ़र करना.
  • ACCESS_FINE_LOCATION ज़रूरी है, क्योंकि Android 11 और इससे पहले के वर्शन वाले डिवाइसों पर, उपयोगकर्ता की जगह की जानकारी इकट्ठा करने के लिए ब्लूटूथ स्कैन का इस्तेमाल किया जा सकता है.

जगह की जानकारी की अनुमतियां, रनटाइम की अनुमतियां होती हैं. इसलिए, आपको रनटाइम के समय इन अनुमतियों के लिए अनुरोध करना होगा. साथ ही, आपको अपने मेनिफ़ेस्ट में इनके बारे में भी जानकारी देनी होगी.

आस-पास मौजूद ब्लूटूथ डिवाइसों के बारे में जानें

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

<manifest>
...
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
...
</manifest>

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

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

<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
...
</manifest>

ऐप्लिकेशन की अनुमतियों के बारे में ज़्यादा जानकारी के लिए, <uses-permission> रेफ़रंस देखें.

ब्लूटूथ की सुविधा के इस्तेमाल के बारे में बताना

अगर ब्लूटूथ आपके ऐप्लिकेशन का अहम हिस्सा है, तो अपनी मेनिफ़ेस्ट फ़ाइल में फ़्लैग जोड़कर इस ज़रूरत के बारे में बताया जा सकता है. <uses-feature> एलिमेंट की मदद से, यह बताया जा सकता है कि आपका ऐप्लिकेशन किस तरह के हार्डवेयर का इस्तेमाल करता है और क्या उसका इस्तेमाल करना ज़रूरी है.

इस उदाहरण में, यह बताने का तरीका बताया गया है कि आपके ऐप्लिकेशन के लिए ब्लूटूथ क्लासिक की ज़रूरत है.

<uses-feature android:name="android.hardware.bluetooth" android:required="true"/>

अगर आपका ऐप्लिकेशन, ब्लूटूथ कम ऊर्जा टेक्नोलॉजी पर निर्भर है, तो इनका इस्तेमाल किया जा सकता है:

<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>

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

रनटाइम के दौरान सुविधा की उपलब्धता देखना

जिन डिवाइसों पर ब्लूटूथ क्लासिक या BLE काम नहीं करता उन पर ऐप्लिकेशन उपलब्ध कराने के लिए, आपको अब भी अपने ऐप्लिकेशन के मेनिफ़ेस्ट में <uses-feature> एलिमेंट को शामिल करते समय, required="false" को सेट करना होगा. इसके बाद, रन-टाइम पर, PackageManager.hasSystemFeature() का इस्तेमाल करके, सुविधा की उपलब्धता का पता लगाया जा सकता है:

Kotlin

// Check to see if the Bluetooth classic feature is available.
val bluetoothAvailable = packageManager.hasSystemFeature(PackageManager.FEATURE_BLUETOOTH)

// Check to see if the BLE feature is available.
val bluetoothLEAvailable = packageManager.hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)

Java

// Use this check to determine whether Bluetooth classic is supported on the device.
// Then you can selectively disable BLE-related features.
boolean bluetoothAvailable = getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH);

// Use this check to determine whether BLE is supported on the device. Then
// you can selectively disable BLE-related features.
boolean bluetoothLEAvailable = getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE);