Permissões do Bluetooth

Para usar recursos do Bluetooth no seu app, é necessário declarar várias permissões. Também é necessário especificar se o app requer compatibilidade com o Bluetooth clássico ou o Bluetooth de baixa energia (BLE). Se o app não exigir o Bluetooth clássico ou o BLE, mas ainda puder se beneficiar dessas tecnologias, verifique a disponibilidade no momento da execução.

Declarar permissões

O conjunto de permissões declaradas no app depende da versão do SDK de destino dele.

Segmentar o Android 12 ou versões mais recentes

Observação : no Android 8.0 (API de nível 26) e versões mais recentes, o Gerenciador de dispositivos complementar (CDM, na sigla em inglês) oferece um método mais simples de conexão com dispositivos complementares em comparação com as permissões descritas nesta seção. O sistema CDM fornece uma interface de pareamento em nome do app e não exige permissões de localização.

Para ter mais controle sobre a experiência de pareamento e conexão, use as permissões descritas nesta seção.

Caixa de diálogo de permissões de Bluetooth
Caixa de diálogo de permissões do sistema, solicitando que o usuário conceda permissão a um app para descobrir, anunciar e se conectar a dispositivos por perto.

Se o app for direcionado ao Android 12 (nível 31 da API) ou versões mais recentes, declare as permissões abaixo no arquivo de manifesto do app:

  1. Se o app procurar dispositivos Bluetooth, como periféricos de BLE, declare a permissão BLUETOOTH_SCAN.
  2. Se o app tornar o dispositivo atual detectável para outros dispositivos Bluetooth, declare a permissão BLUETOOTH_ADVERTISE.
  3. Se o app se comunicar com dispositivos Bluetooth já pareados, declare a permissão BLUETOOTH_CONNECT.
  4. Para as declarações de permissões legadas relacionadas ao Bluetooth, defina android:maxSdkVersion como 30. Essa etapa de compatibilidade do app ajuda o sistema a conceder ao app apenas as permissões de Bluetooth necessárias quando instalado em dispositivos com o Android 12 ou versões mais recentes.
  5. Se o app usa resultados da verificação por Bluetooth para determinar a localização física, declare a permissão ACCESS_FINE_LOCATION. Caso contrário, você pode declarar que o app não determina a localização física.

As permissões BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT e BLUETOOTH_SCAN são permissões de execução. Portanto, você precisa solicitar a aprovação do usuário explicitamente no seu app antes de procurar dispositivos Bluetooth, tornar um dispositivo detectável para outros dispositivos ou se comunicar com dispositivos Bluetooth já pareados. Quando o app solicita pelo menos uma dessas permissões, o sistema solicita que o usuário autorize o acesso do app a Dispositivos por perto, como mostrado na Figura 1.

O snippet de código a seguir demonstra como declarar permissões relacionadas ao Bluetooth no app caso ele seja destinado ao Android 12 ou versões mais recentes:

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

Declarar explicitamente que o app não determina a localização física

Se o app não usa os resultados da verificação por Bluetooth para determinar a localização física, você pode declarar que o app nunca usa as permissões de Bluetooth para determinar a localização física. Para isso, siga estas etapas:

  1. Adicione o atributo android:usesPermissionFlags à declaração de permissão BLUETOOTH_SCAN e defina o valor dele como neverForLocation.

  2. Se a localização não for necessária para o app, remova a permissão ACCESS_FINE_LOCATION do manifesto.

O snippet de código a seguir mostra como atualizar o arquivo de manifesto do 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" />

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

Segmentar o Android 11 ou versões anteriores

Se o app for direcionado ao Android 11 (nível 30 da API) ou versões anteriores, declare as permissões abaixo no arquivo de manifesto do app:

  • O BLUETOOTH é necessário para executar qualquer comunicação Bluetooth clássica ou BLE, como solicitar uma conexão, aceitar uma conexão e transferir dados.
  • A ACCESS_FINE_LOCATION é necessária porque, no Android 11 e versões anteriores, uma verificação por Bluetooth pode ser usada para coletar informações sobre a localização do usuário.

Como as permissões de localização são permissões de execução, é necessário solicitá-las no momento da execução e declará-las no manifesto.

Descobrir dispositivos Bluetooth locais

Se você quiser que seu app inicie a descoberta de dispositivos ou manipule as configurações de Bluetooth, declare a permissão BLUETOOTH_ADMIN. A maioria dos apps precisa dessa permissão apenas para descobrir dispositivos Bluetooth locais. Não use as outras habilidades concedidas por essa permissão, a menos que o app seja um "gerenciador de energia" que modifique as configurações do Bluetooth mediante solicitação do usuário. Declare a permissão no arquivo de manifesto do app. Por exemplo:

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

Se o app oferece suporte a um serviço e pode ser executado no Android 10 (API de nível 29) ou no Android 11, é necessário declarar também a permissão ACCESS_BACKGROUND_LOCATION para descobrir dispositivos Bluetooth. Para mais informações sobre esse requisito, consulte Acessar a localização em segundo plano.

O snippet de código a seguir mostra como declarar a permissão ACCESS_BACKGROUND_LOCATION:

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

Consulte a referência <uses-permission> para mais informações sobre como declarar permissões do app.

Especificar o uso do recurso Bluetooth

Se o Bluetooth for uma parte essencial do seu app, adicione flags ao arquivo de manifesto indicando esse requisito. O elemento <uses-feature> permite especificar o tipo de hardware usado pelo app e se ele é necessário ou não.

Este exemplo mostra como indicar que o Bluetooth clássico é necessário para seu app.

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

Se seu aplicativo depende do Bluetooth Low Energy, você pode usar o seguinte:

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

Se você disser que o recurso é necessário para seu app, a Google Play Store vai ocultar o app dos usuários em dispositivos sem esses recursos. Por esse motivo, defina o atributo necessário como true apenas se o app não puder funcionar sem o recurso.

Verificar a disponibilidade dos recursos no momento da execução

Para disponibilizar o app para dispositivos sem suporte ao Bluetooth clássico ou BLE, ainda é necessário incluir o elemento <uses-feature> no manifesto do app, mas defina required="false". Em seguida, no ambiente de execução, é possível determinar a disponibilidade do recurso usando PackageManager.hasSystemFeature():

Kotlin

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