مجوزهای بلوتوث

برای استفاده از ویژگی‌های بلوتوث در برنامه خود، باید چندین مجوز را اعلام کنید . همچنین باید مشخص کنید که آیا برنامه شما به پشتیبانی از بلوتوث کلاسیک یا بلوتوث کم‌مصرف (BLE) نیاز دارد یا خیر . اگر برنامه شما به بلوتوث کلاسیک یا BLE نیاز ندارد اما همچنان می‌تواند از این فناوری‌ها بهره‌مند شود، می‌توانید در زمان اجرا، در دسترس بودن آنها را بررسی کنید .

اعلام مجوزها

مجموعه مجوزهایی که در برنامه خود اعلام می‌کنید، به نسخه SDK هدف برنامه شما بستگی دارد.

اندروید ۱۲ یا بالاتر را هدف قرار دهید

اگر برنامه شما اندروید ۱۲ (سطح API 31) یا بالاتر را هدف قرار می‌دهد، مجوزهای زیر را در فایل مانیفست برنامه خود اعلام کنید:

1. اگر برنامه شما به دنبال دستگاه‌های بلوتوث مانند لوازم جانبی BLE می‌گردد ، مجوز BLUETOOTH_SCAN را اعلام کنید.
2. اگر برنامه شما دستگاه فعلی را برای سایر دستگاه‌های بلوتوث قابل شناسایی می‌کند ، مجوز BLUETOOTH_ADVERTISE را اعلام کنید.
3. اگر برنامه شما با دستگاه‌های بلوتوث از قبل جفت‌شده ارتباط برقرار می‌کند ، مجوز BLUETOOTH_CONNECT را اعلام کنید.
4. برای اعلان‌های مجوز مربوط به بلوتوث قدیمی خود، android:maxSdkVersion را روی 30 تنظیم کنید. این مرحله سازگاری برنامه به سیستم کمک می‌کند تا فقط مجوزهای بلوتوثی را که برنامه شما هنگام نصب روی دستگاه‌هایی که اندروید 12 یا بالاتر را اجرا می‌کنند، نیاز دارد، به آن اعطا کند.
5. اگر برنامه شما از نتایج اسکن بلوتوث برای استخراج موقعیت مکانی فیزیکی استفاده می‌کند، مجوز ACCESS_FINE_LOCATION تعریف کنید. در غیر این صورت، می‌توانید قویاً ادعا کنید که برنامه شما موقعیت مکانی فیزیکی را استخراج نمی‌کند و android:maxSdkVersion برای مجوز ACCESS_FINE_LOCATION روی 30 تنظیم کنید.

مجوزهای BLUETOOTH_ADVERTISE ، BLUETOOTH_CONNECT و BLUETOOTH_SCAN مجوزهای زمان اجرا هستند. بنابراین، قبل از اینکه بتوانید دستگاه‌های بلوتوث را جستجو کنید، دستگاهی را برای سایر دستگاه‌ها قابل شناسایی کنید یا با دستگاه‌های بلوتوث جفت‌شده ارتباط برقرار کنید، باید صریحاً در برنامه خود از کاربر تأییدیه بگیرید . هنگامی که برنامه شما حداقل یکی از این مجوزها را درخواست می‌کند، سیستم از کاربر می‌خواهد که به برنامه شما اجازه دسترسی به دستگاه‌های نزدیک را بدهد، همانطور که در شکل 1 نشان داده شده است.

قطعه کد زیر نحوه اعلان مجوزهای مربوط به بلوتوث را در برنامه شما، در صورتی که اندروید ۱۲ یا بالاتر را هدف قرار داده باشد، نشان می‌دهد:

<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. ویژگی android:usesPermissionFlags را به اعلان مجوز BLUETOOTH_SCAN خود اضافه کنید و مقدار این ویژگی را روی neverForLocation تنظیم کنید.

2. اگر برنامه شما به موقعیت مکانی نیازی ندارد، مجوز ACCESS_FINE_LOCATION را از فایل manifest برنامه خود حذف کنید.

قطعه کد زیر نحوه به‌روزرسانی فایل مانیفست برنامه شما را نشان می‌دهد:

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

اندروید ۱۱ یا پایین‌تر را هدف قرار دهید

اگر برنامه شما اندروید ۱۱ (سطح API 30) یا پایین‌تر را هدف قرار می‌دهد، مجوزهای زیر را در فایل مانیفست برنامه خود اعلام کنید:

• BLUETOOTH برای انجام هرگونه ارتباط بلوتوث کلاسیک یا BLE، مانند درخواست اتصال، پذیرش اتصال و انتقال داده، ضروری است.
• ACCESS_FINE_LOCATION ضروری است زیرا در اندروید ۱۱ و پایین‌تر، اسکن بلوتوث می‌تواند به طور بالقوه برای جمع‌آوری اطلاعات در مورد موقعیت مکانی کاربر استفاده شود.

از آنجا که مجوزهای موقعیت مکانی ، مجوزهای زمان اجرا هستند، شما باید این مجوزها را در زمان اجرا و همراه با اعلام آنها در مانیفست خود درخواست کنید .

دستگاه‌های بلوتوث محلی را کشف کنید

اگر می‌خواهید برنامه شما قابلیت کشف دستگاه یا دستکاری تنظیمات بلوتوث را داشته باشد، باید مجوز BLUETOOTH_ADMIN را تعریف کنید. اکثر برنامه‌ها صرفاً برای قابلیت کشف دستگاه‌های بلوتوث محلی به این مجوز نیاز دارند. از سایر قابلیت‌های اعطا شده توسط این مجوز استفاده نکنید، مگر اینکه برنامه یک "مدیر برق" باشد که تنظیمات بلوتوث را بنا به درخواست کاربر تغییر می‌دهد. این مجوز را در فایل مانیفست برنامه خود تعریف کنید. برای مثال:

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

اگر برنامه شما از یک سرویس پشتیبانی می‌کند و می‌تواند روی اندروید ۱۰ (سطح API ۲۹) یا اندروید ۱۱ اجرا شود، باید مجوز 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"/>

اگر بگویید که این ویژگی برای برنامه شما ضروری است، فروشگاه گوگل پلی برنامه شما را از کاربران دستگاه‌های فاقد آن ویژگی پنهان می‌کند. به همین دلیل، فقط در صورتی باید ویژگی required را روی true تنظیم کنید که برنامه شما بدون آن ویژگی کار نکند.

بررسی در دسترس بودن ویژگی‌ها در زمان اجرا

برای اینکه برنامه شما برای دستگاه‌هایی که از بلوتوث کلاسیک یا BLE پشتیبانی نمی‌کنند، در دسترس باشد، باید عنصر <uses-feature> را در مانیفست برنامه خود قرار دهید، اما آن را required="false" قرار دهید. سپس، در زمان اجرا، می‌توانید با استفاده از PackageManager.hasSystemFeature() در دسترس بودن ویژگی را تعیین کنید:

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

// 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);