Разрешения Bluetooth

Чтобы использовать функции Bluetooth в вашем приложении, необходимо объявить несколько разрешений . Также следует указать, требуется ли вашему приложению поддержка Bluetooth Classic или Bluetooth Low Energy (BLE). Если вашему приложению не требуется поддержка Bluetooth Classic или BLE, но вы всё равно можете использовать эти технологии, вы можете проверить их доступность во время выполнения .

Объявить разрешения

Набор разрешений, которые вы объявляете в своем приложении, зависит от целевой версии SDK вашего приложения.

Целевая версия Android 12 или выше

Если ваше приложение предназначено для Android 12 (уровень API 31) или выше, укажите следующие разрешения в файле манифеста вашего приложения:

1. Если ваше приложение ищет устройства Bluetooth , такие как периферийные устройства BLE, объявите разрешение BLUETOOTH_SCAN .
2. Если ваше приложение делает текущее устройство видимым для других устройств Bluetooth , объявите разрешение BLUETOOTH_ADVERTISE .
3. Если ваше приложение взаимодействует с уже сопряженными устройствами Bluetooth , объявите разрешение BLUETOOTH_CONNECT .
4. Для устаревших деклараций разрешений, связанных с Bluetooth, установите android:maxSdkVersion значение 30. Этот шаг обеспечения совместимости приложений помогает системе предоставлять вашему приложению только необходимые ему разрешения Bluetooth при установке на устройствах под управлением Android 12 или более поздней версии.
5. Если ваше приложение использует результаты сканирования Bluetooth для определения физического местоположения, объявите разрешение ACCESS_FINE_LOCATION . В противном случае вы можете однозначно заявить, что ваше приложение не определяет физическое местоположение , и установить значение android:maxSdkVersion равным 30 для разрешения ACCESS_FINE_LOCATION .

Разрешения BLUETOOTH_ADVERTISE , BLUETOOTH_CONNECT и BLUETOOTH_SCAN являются разрешениями времени выполнения . Поэтому необходимо явно запросить одобрение пользователя в приложении, прежде чем вы сможете искать устройства Bluetooth, делать устройство видимым для других устройств или взаимодействовать с уже сопряженными устройствами Bluetooth. Когда приложение запрашивает хотя бы одно из этих разрешений, система предлагает пользователю разрешить приложению доступ к устройствам поблизости , как показано на рисунке 1.

В следующем фрагменте кода показано, как объявить разрешения, связанные с Bluetooth, в вашем приложении, если оно предназначено для 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>

Настоятельно заявите, что ваше приложение не определяет физическое местоположение.

Если ваше приложение не использует результаты сканирования Bluetooth для определения физического местоположения, вы можете с уверенностью утверждать, что ваше приложение никогда не использует разрешения Bluetooth для определения физического местоположения. Для этого выполните следующие действия:

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 (уровень API 30) или ниже, укажите следующие разрешения в файле манифеста вашего приложения:

• BLUETOOTH необходим для осуществления любой связи по классическому Bluetooth или BLE, например, запроса соединения, принятия соединения и передачи данных.
• ACCESS_FINE_LOCATION необходим, поскольку на устройствах Android 11 и ниже сканирование Bluetooth потенциально может использоваться для сбора информации о местоположении пользователя.

Поскольку разрешения на местоположение являются разрешениями времени выполнения , вы должны запросить эти разрешения во время выполнения, а также объявить их в своем манифесте.

Обнаружение локальных устройств Bluetooth

Если вы хотите, чтобы ваше приложение инициировало обнаружение устройств или изменяло настройки Bluetooth, необходимо объявить разрешение BLUETOOTH_ADMIN . Большинству приложений это разрешение необходимо исключительно для обнаружения локальных устройств Bluetooth. Не используйте другие возможности, предоставляемые этим разрешением, если только приложение не является «менеджером питания», изменяющим настройки Bluetooth по запросу пользователя. Объявите это разрешение в файле манифеста вашего приложения. Например:

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

Если ваше приложение поддерживает службу и может работать на Android 10 (API уровня 29) или Android 11, необходимо также объявить разрешение ACCESS_BACKGROUND_LOCATION для обнаружения устройств Bluetooth. Подробнее об этом требовании см. в разделе Доступ к данным о местоположении в фоновом режиме .

В следующем фрагменте кода показано, как объявить разрешение ACCESS_BACKGROUND_LOCATION :

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

Дополнительную информацию об объявлении разрешений приложения см. в справочнике <uses-permission> .

Укажите использование функции Bluetooth

Если Bluetooth — критически важный компонент вашего приложения, вы можете добавить флаги в файл манифеста, указывающие на это требование. Элемент <uses-feature> позволяет указать тип оборудования, используемого вашим приложением, и необходимость его использования.

В этом примере показано, как указать, что для вашего приложения требуется Bluetooth Classic.

<uses-feature android:name="android.hardware.bluetooth" android:required="true"/>

Если ваше приложение использует Bluetooth Low Energy, вы можете использовать следующее:

<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>

Если вы укажете, что эта функция обязательна для вашего приложения, то магазин Google Play скроет его от пользователей на устройствах, где она отсутствует. Поэтому вам следует устанавливать атрибут required в true только в том случае, если ваше приложение не может работать без этой функции.

Проверить доступность функции во время выполнения

Чтобы сделать приложение доступным для устройств, не поддерживающих Bluetooth Classic или 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);