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

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

अनुमतियों की जानकारी देना

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

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

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

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

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

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

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

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

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

<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 पर सेट करें.

   ध्यान दें: अगर आपने neverForLocation को अपने android:usesPermissionFlags में शामिल किया है, तो स्कैन के नतीजों से कुछ बीएलई बीकन फ़िल्टर कर दिए जाते हैं.

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" />

    <!-- Set maxSdkVersion to 30 if you can strongly assert that, on
         Android 12 and higher, your app never derives physical location from
         Bluetooth scan results and doesn't need location access for any other
         purpose. -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                     android:maxSdkVersion="30" />
    ...
</manifest>

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

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

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

ध्यान दें: Android 8.0 या इसके बाद के वर्शन पर काम करने वाले डिवाइसों पर, CompanionDeviceManager का इस्तेमाल किया जा सकता है. इससे, जगह की जानकारी ऐक्सेस करने की अनुमति के बिना, अपने ऐप्लिकेशन की ओर से आस-पास मौजूद कंपैनियन डिवाइसों को स्कैन किया जा सकता है. इस विकल्प के बारे में ज़्यादा जानने के लिए, कंपैनियन डिवाइस को पेयर करना लेख पढ़ें.

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

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

अगर आपको अपने ऐप्लिकेशन को डिवाइस खोजने या ब्लूटूथ सेटिंग में बदलाव करने की अनुमति देनी है, तो आपको 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> एलिमेंट की मदद से, यह बताया जा सकता है कि आपका ऐप्लिकेशन किस तरह के हार्डवेयर का इस्तेमाल करता है. साथ ही, यह भी बताया जा सकता है कि यह हार्डवेयर ज़रूरी है या नहीं.

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

<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 पर सेट करना चाहिए, जब आपका ऐप्लिकेशन इस सुविधा के बिना काम न कर सके.

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

अगर आपको अपने ऐप्लिकेशन को उन डिवाइसों के लिए उपलब्ध कराना है जिन पर ब्लूटूथ क्लासिक या बीएलई काम नहीं करता है, तो आपको अपने ऐप्लिकेशन के मेनिफ़ेस्ट में <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);