Разрешения Bluetooth

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

Объявить права доступа

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

Целевая платформа: Android 12 или выше

Примечание: В Android 8.0 (уровень API 26) и выше Companion Device Manager (CDM) предоставляет более простой способ подключения к сопутствующим устройствам по сравнению с разрешениями, описанными в этом разделе. Система CDM предоставляет пользовательский интерфейс сопряжения от имени вашего приложения и не требует разрешений на определение местоположения.

Если вам нужен более полный контроль над процессом сопряжения и подключения, используйте разрешения, описанные в этом разделе.

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

Если ваше приложение ориентировано на 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 Classic или 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 или 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)

Java 

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