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

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

اعلام اجازه‌ها

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

Android 12 یا بالاتر را هدف قرار دهید

اگر برنامه شما Android 12 (سطح میانای برنامه‌سازی کاربردی ۳۱) یا بالاتر را هدف قرار می‌دهد، اجازه‌های زیر را در فایل مانیفست برنامه‌تان اعلام کنید:

1. اگر برنامه‌تان دستگاه‌های بلوتوث، مثل دستگاه‌های جانبی BLE، را جستجو می‌کند، اجازه BLUETOOTH_SCAN را اعلام کنید.
2. اگر برنامه‌تان دستگاه فعلی را برای سایر دستگاه‌های بلوتوث یافتنی می‌کند، اجازه BLUETOOTH_ADVERTISE را اعلام کنید.
3. اگر برنامه‌تان با دستگاه‌های بلوتوثی که قبلاً جفت شده‌اند ارتباط برقرار می‌کند، اجازه BLUETOOTH_CONNECT را اعلام کنید.
4. برای اعلامیه‌های اجازه مربوط به بلوتوث قدیمی، android:maxSdkVersion را روی ۳۰ تنظیم کنید. این مرحله سازگاری برنامه به سیستم کمک می‌کند فقط اجازه‌های بلوتوثی را که برنامه‌تان هنگام نصب در دستگاه‌های دارای Android نسخه ۱۲ یا بالاتر نیاز دارد به آن اعطا کند.
5. اگر برنامه‌تان از نتایج اسکن بلوتوث برای به‌دست آوردن مکان فیزیکی استفاده می‌کند، اجازه 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>

قویاً تأکید کنید که برنامه‌تان مکان فیزیکی را استخراج نمی‌کند

اگر برنامه‌تان از نتایج اسکن بلوتوث برای به‌دست آوردن مکان فیزیکی استفاده نمی‌کند، می‌توانید به‌طور قطعی اعلام کنید که برنامه‌تان هرگز از اجازه‌های بلوتوث برای به‌دست آوردن مکان فیزیکی استفاده نمی‌کند. برای انجام این کار، مراحل زیر را تکمیل کنید:

1. مشخصه android:usesPermissionFlags را به اظهارنامه اجازه BLUETOOTH_SCAN اضافه کنید و مقدار این مشخصه را روی 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" />

    <!-- 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 (سطح میانای برنامه‌سازی کاربردی ۳۰) یا پایین‌تر را هدف قرار می‌دهد، اجازه‌های زیر را در فایل مانیفست برنامه‌تان اعلام کنید:

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