برای استفاده از ویژگیهای بلوتوث در برنامهتان، باید چندین اجازه را اعلام کنید. همچنین باید مشخص کنید که آیا برنامهتان به پشتیبانی از بلوتوث کلاسیک یا بلوتوث کممصرف (BLE) نیاز دارد یا نه. اگر برنامهتان به بلوتوث کلاسیک یا بلوتوث کممصرف نیاز ندارد اما همچنان میتواند از این فناوریها بهرهمند شود، میتوانید در زمان اجرا دردسترس بودن را بررسی کنید.
اعلام اجازهها
مجموعه اجازههایی که در برنامهتان اعلام میکنید به نسخه کیت توسعه نرمافزار هدف برنامهتان بستگی دارد.
Android 12 یا بالاتر را هدف قرار دهید
اگر برنامه شما Android 12 (سطح میانای برنامهسازی کاربردی ۳۱) یا بالاتر را هدف قرار میدهد، اجازههای زیر را در فایل مانیفست برنامهتان اعلام کنید:
- اگر برنامهتان دستگاههای بلوتوث را جستجو میکند، مثلاً لوازم جانبی BLE،
اجازه
BLUETOOTH_SCANرا اعلام کنید. - اگر برنامهتان دستگاه فعلی را برای سایر دستگاههای بلوتوث قابلشناسایی میکند،
اجازه
BLUETOOTH_ADVERTISEرا اعلام کنید. - اگر برنامهتان با دستگاههای بلوتوثی که قبلاً جفت شدهاند ارتباط برقرار میکند،
اجازه
BLUETOOTH_CONNECTرا اعلام کنید. - برای بیانیههای اجازه مربوط به بلوتوث قدیمی،
android:maxSdkVersionرا روی ۳۰ تنظیم کنید. این مرحله سازگاری برنامه به سیستم کمک میکند فقط اجازههای بلوتوثی را که برنامهتان هنگام نصب در دستگاههای دارای Android نسخه ۱۲ یا بالاتر نیاز دارد به آن اعطا کند. - اگر برنامهتان از نتایج اسکن بلوتوث برای بهدست آوردن مکان فیزیکی استفاده میکند،
اجازه
ACCESS_FINE_LOCATIONرا اعلام کنید. درغیراینصورت، میتوانید قویاً ادعا کنید که برنامهتان مکان فیزیکی را استخراج نمیکند وandroid:maxSdkVersionرا برای اجازه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>
قویاً تأکید کنید که برنامهتان مکان فیزیکی را استخراج نمیکند
اگر برنامهتان از نتایج اسکن بلوتوث برای بهدست آوردن مکان فیزیکی استفاده نمیکند، میتوانید بهطور قطعی اعلام کنید که برنامهتان هرگز از اجازههای بلوتوث برای بهدست آوردن مکان فیزیکی استفاده نمیکند. برای انجام این کار، مراحل زیر را تکمیل کنید:
مشخصه
android:usesPermissionFlagsرا به اظهارنامه اجازهBLUETOOTH_SCANاضافه کنید و مقدار این مشخصه را رویneverForLocationتنظیم کنید.اگر برنامه شما به مکان نیاز ندارد، اجازه
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برای انجام هرگونه ارتباط بلوتوث کلاسیک یا BLE، مانند درخواست اتصال، پذیرش اتصال، و انتقال داده، ضروری است.ACCESS_FINE_LOCATIONضروری است زیرا در Android نسخه ۱۱ و پایینتر، اسکن دستگاههای بلوتوث بهطور بالقوه میتواند برای جمعآوری اطلاعات درباره مکان کاربر استفاده شود.
چون اجازههای مکان اجازههای زمان اجرا هستند، باید علاوهبر اعلام آنها در مانیفست، این اجازهها را در زمان اجرا درخواست کنید.
کاوش دستگاههای بلوتوث محلی
اگر میخواهید برنامهتان کاوش دستگاه را آغاز کند یا تنظیمات بلوتوث را دستکاری کند، باید اجازه BLUETOOTH_ADMIN را اعلام کنید. اکثر برنامهها
این اجازه را صرفاً برای توانایی شناسایی دستگاههای بلوتوث محلی نیاز دارند.
از سایر تواناییهای اعطاشده توسط این اجازه استفاده نکنید، مگراینکه برنامه یک
«مدیر مصرف باتری» باشد که تنظیمات بلوتوث را براساس درخواست کاربر تغییر میدهد. اجازه
را در فایل مانیفست برنامهتان اعلام کنید. برای مثال:
<manifest>
...
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
...
</manifest>
اگر برنامهتان از سرویسی پشتیبانی میکند و میتواند در Android 10 (سطح میانای برنامهسازی کاربردی ۲۹) یا
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»
برنامهتان را از دید کاربرانی که دستگاهشان فاقد این ویژگیها است پنهان میکند. به همین دلیل،
فقط درصورتی باید مشخصه الزامی را روی 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);