Permissões do Bluetooth

Para usar recursos do Bluetooth no app, é necessário declarar várias permissões. Você também precisa especificar se o app exige suporte ao Bluetooth clássico ou ao 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, você poderá verificar a disponibilidade no momento da execução.

Declarar permissões

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

Segmentar o Android 12 ou versões mais recentes

Caso o app seja destinado ao Android 12 (nível 31 da API) ou mais recente, 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 de Bluetooth necessárias no momento da instalação em dispositivos com o Android 12 ou mais recente.
5. Se o app usa os resultados da verificação Bluetooth para determinar a localização física, declare a permissão ACCESS_FINE_LOCATION. Caso contrário, é possível afirmar explicitamente 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 app antes de procurar dispositivos Bluetooth, tornar um dispositivo detectável para outros 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 permita 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 se ele for 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 resultados da verificação Bluetooth para determinar a localização física, é possível afirmar que o app nunca usa as permissões 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 seguintes permissões no arquivo de manifesto do app:

• O BLUETOOTH é necessário para realizar qualquer comunicação do Bluetooth Classic 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 Bluetooth pode ser usada para coletar informações sobre o local do usuário.

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

Descobrir 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 poder 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 oferecer suporte a um serviço e puder ser executado no Android 10 (nível 29 da API) ou no Android 11, também será 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, adicione flags ao arquivo de manifesto para indicar esse requisito. O elemento <uses-feature> permite especificar o tipo de hardware usado pelo app e se ele é obrigatório.

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 o app depender do Bluetooth de baixa energia, você poderá usar o seguinte:

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

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

Verificar a disponibilidade dos recursos durante a execução

Para disponibilizar o app a dispositivos que não oferecem suporte ao Bluetooth clássico ou ao BLE, ainda será necessário incluir o elemento <uses-feature> no manifesto do app, mas defina required="false". Em seguida, no tempo 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);