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

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

مجوزها را اعلام کنید

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

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

توجه: در Android 8.0 (سطح API 26) و بالاتر، Companion Device Manager (CDM) روش ساده‌تری برای اتصال به دستگاه‌های همراه در مقایسه با مجوزهای توضیح داده شده در این بخش ارائه می‌کند. سیستم CDM یک رابط کاربری جفت‌سازی از طرف برنامه شما ارائه می‌کند و به مجوزهای مکان نیاز ندارد.

اگر می خواهید کنترل بیشتری بر تجربه جفت شدن و اتصال داشته باشید، از مجوزهای توضیح داده شده در این بخش استفاده کنید.

گفتگوی مجوزهای بلوتوث
گفتگوی مجوزهای سیستم، از کاربر می‌خواهد به یک برنامه اجازه دهد تا دستگاه‌های اطراف را کشف، تبلیغ کند و به آن متصل شود.

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

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

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

قطعه کد زیر نحوه اعلام مجوزهای مربوط به بلوتوث را در برنامه خود در صورتی که اندروید 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" />

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

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

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

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

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

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

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

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

اگر برنامه شما از سرویسی پشتیبانی می‌کند و می‌تواند روی Android 10 (سطح API 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 برنامه شما را از کاربران دستگاه‌هایی که فاقد این ویژگی‌ها هستند پنهان می‌کند. به همین دلیل، فقط در صورتی باید ویژگی مورد نیاز را روی 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);