Permissões do Bluetooth

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

Declarar permissões

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

Segmentar o Android 12 ou mais recente

Caso o app seja destinado ao Android 12 (nível 31 da API) ou versões mais recentes, declare as seguintes permissões no arquivo de manifesto do app:

1. Se o app procurar dispositivos Bluetooth, como periféricos 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 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 Bluetooth para obter a localização física, declare a permissão ACCESS_FINE_LOCATION. Caso contrário, é possível declarar fortemente que seu app não deriva a localização física.

As permissões BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT e BLUETOOTH_SCAN são permissões de execução. Portanto, é necessário 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 pede para que o app acesse Dispositivos por perto, conforme mostrado na Figura 1.

O snippet de código abaixo 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 derivar a localização física, é possível fazer uma declaração forte de que o app nunca usa as permissões do Bluetooth para acessar 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 uma versão anterior

Se o app for direcionado ao Android 11 (nível 30 da API) ou versões anteriores, declare as seguintes permissões 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.
• ACCESS_FINE_LOCATION é necessário 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 solicitar essas permissões durante a execução e declará-las no manifesto.

Descubra dispositivos Bluetooth locais

Se você quiser que o app inicie a descoberta de dispositivos ou manipule as configurações do Bluetooth, declare a permissão BLUETOOTH_ADMIN. A maioria dos apps precisa dessa permissão apenas para descobrir dispositivos Bluetooth locais. Não use os outros recursos concedidos 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 (nível 29 da API) ou no Android 11, também é necessário declarar 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 abaixo 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 app, você poderá adicionar flags ao arquivo de manifesto indicando esse requisito. O elemento <uses-feature> permite especificar o tipo de hardware que o app usa e se ele é obrigatório ou não.

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

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

Se seu app depende do Bluetooth de baixa energia, você pode usar o seguinte:

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

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

Verificar a disponibilidade do recurso no momento da execução

Para disponibilizar o app para dispositivos sem suporte ao Bluetooth clássico ou BLE, inclua 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():

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