Permisos de Bluetooth

Para usar las funciones de Bluetooth en tu app, debes declarar varios permisos. También debes especificar si tu app requiere compatibilidad con Bluetooth clásico o Bluetooth de bajo consumo (BLE). Si tu app no requiere Bluetooth clásico ni BLE, pero puede beneficiarse de estas tecnologías, puedes verificar la disponibilidad durante el tiempo de ejecución.

Cómo declarar permisos

El conjunto de permisos que declares en tu app dependerá de la versión del SDK de destino de tu app.

Segmenta tus anuncios para Android 12 o versiones posteriores

Si tu app se orienta a Android 12 (nivel de API 31) o versiones posteriores, declara los siguientes permisos en el archivo de manifiesto de la app:

1. Si tu app busca dispositivos Bluetooth, como periféricos BLE, declara el permiso BLUETOOTH_SCAN.
2. Si tu app hace que el dispositivo actual sea visible para otros dispositivos Bluetooth, declara el permiso BLUETOOTH_ADVERTISE.
3. Si tu app se comunica con dispositivos Bluetooth ya vinculados, declara el permiso BLUETOOTH_CONNECT.
4. Para tus declaraciones de permisos heredados relacionados con Bluetooth, establece android:maxSdkVersion en 30. Este paso de compatibilidad de la app ayuda al sistema a otorgarle a tu app solo los permisos de Bluetooth que necesita cuando se instala en dispositivos que ejecutan Android 12 o versiones posteriores.
5. Si tu app usa los resultados de la búsqueda de dispositivos Bluetooth para obtener la ubicación física, declara el permiso ACCESS_FINE_LOCATION. De lo contrario, puedes declarar que la app no obtiene ubicación física y establecer android:maxSdkVersion en 30 para el permiso ACCESS_FINE_LOCATION.

Los permisos BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT y BLUETOOTH_SCAN son permisos de tiempo de ejecución. Por lo tanto, debes solicitar explícitamente la aprobación del usuario en tu app antes de poder buscar dispositivos Bluetooth, hacer que un dispositivo sea detectable para otros dispositivos o comunicarte con dispositivos Bluetooth ya vinculados. Cuando tu app solicita al menos uno de estos permisos, el sistema le pide al usuario que permita que la app acceda a los dispositivos cercanos, como se muestra en la figura 1.

En el siguiente fragmento de código, se muestra cómo declarar permisos relacionados con Bluetooth en tu app si se orienta a Android 12 o versiones posteriores:

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

Declara que la app no obtiene ubicación física

Si tu app no usa los resultados de la búsqueda de dispositivos Bluetooth para obtener la ubicación física, puedes declarar con firmeza que nunca usa los permisos de Bluetooth para obtener la ubicación física. Para ello, completa los siguientes pasos:

1. Agrega el atributo android:usesPermissionFlags a la declaración de permisos BLUETOOTH_SCAN y configura el valor de este atributo en neverForLocation.

2. De lo contrario, si no se necesita otra ubicación para la app, quita el permiso ACCESS_FINE_LOCATION del manifiesto de esta.

En el siguiente fragmento de código, se muestra cómo actualizar el archivo de manifiesto de la app:

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

Orienta tu app a Android 11 o versiones anteriores

Si tu app se orienta a Android 11 (nivel de API 30) o versiones anteriores, declara los siguientes permisos en el archivo de manifiesto de la app:

• BLUETOOTH es necesario para realizar cualquier comunicación Bluetooth clásica o BLE, como solicitar una conexión, aceptar una conexión y transferir datos.
• ACCESS_FINE_LOCATION es necesario porque, en Android 11 y versiones anteriores, se podría usar una búsqueda de dispositivos Bluetooth para recopilar información sobre la ubicación del usuario.

Debido a que los permisos de ubicación son permisos de tiempo de ejecución, debes solicitarlos en el tiempo de ejecución y declararlos en el manifiesto.

Descubrir dispositivos Bluetooth locales

Si quieres que tu app inicie la detección de dispositivos o manipule la configuración de Bluetooth, debes declarar el permiso BLUETOOTH_ADMIN. La mayoría de las apps necesitan este permiso solo para poder descubrir dispositivos Bluetooth locales. No uses las otras capacidades que otorga este permiso, a menos que la app sea un "administrador de energía" que modifique la configuración de Bluetooth cuando el usuario lo solicite. Declara el permiso en el archivo de manifiesto de tu app. Por ejemplo:

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

Si tu app admite un servicio y se puede ejecutar en Android 10 (nivel de API 29) o Android 11, también debes declarar el permiso ACCESS_BACKGROUND_LOCATION para descubrir dispositivos Bluetooth. Para obtener más información sobre este requisito, consulta Cómo acceder a la ubicación en segundo plano.

En el siguiente fragmento de código, se muestra cómo declarar el permiso ACCESS_BACKGROUND_LOCATION:

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

Consulta la referencia de <uses-permission> para obtener más información sobre cómo declarar los permisos de la app.

Especifica el uso de la función de Bluetooth

Si el Bluetooth es una parte fundamental de tu app, puedes agregar marcas al archivo de manifiesto para indicar este requisito. El elemento <uses-feature> te permite especificar el tipo de hardware que usa tu app y si es obligatorio o no.

En este ejemplo, se muestra cómo indicar que se requiere Bluetooth clásico para tu app.

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

Si tu app depende del Bluetooth de bajo consumo, puedes usar lo siguiente:

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

Si indicas que la función es obligatoria para tu app, Google Play Store ocultará la app a los usuarios que tengan dispositivos que no cuenten con esas funciones. Por este motivo, solo debes establecer el atributo requerido en true si tu app no puede funcionar sin la función.

Cómo verificar la disponibilidad de las funciones durante el tiempo de ejecución

Para que tu app esté disponible en dispositivos que no admiten Bluetooth clásico ni BLE, debes incluir el elemento <uses-feature> en el manifiesto de la app, pero establecer required="false". Luego, en el entorno de ejecución, puedes determinar la disponibilidad de las funciones con 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);