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 que você declara no app depende da versão do SDK de destino.

Segmentar o Android 12 ou mais recente

Se o app for direcionado 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 BLUETOOTH_SCAN permissão.
2. Se o app tornar o dispositivo atual detectável para outros dispositivos Bluetooth dispositivos, declare a BLUETOOTH_ADVERTISE permissão.
3. Se o app se comunicar com dispositivos Bluetooth já pareados, declare a BLUETOOTH_CONNECT permissão.
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 usar resultados da verificação Bluetooth para determinar a localização física, declare a ACCESS_FINE_LOCATION permissão. Caso contrário, você pode declarar explicitamente que o app não determina a localização física e definir android:maxSdkVersion como 30 para a permissão ACCESS_FINE_LOCATION.

As permissões BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT e BLUETOOTH_SCAN são permissões de execução. Portanto, é necessário solicitar explicitamente a aprovação do usuário no 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 solicitar pelo menos uma dessas permissões, o sistema solicitará que o usuário permita que o app acesse os Dispositivos por perto, conforme mostrado na Figura 1.

O snippet de código a seguir demonstra como declarar permissões relacionadas ao Bluetooth no app se ele for direcionado ao Android 12 ou mais recente:

<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 usar resultados da verificação Bluetooth para determinar a localização física, você poderá declarar explicitamente 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" />

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

Segmentar o Android 11 ou versões anteriores

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

• BLUETOOTH é necessário para realizar 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 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 além de declará-las no manifesto.

Descobrir dispositivos Bluetooth locais

Se você quiser que o app inicie a descoberta de dispositivos ou manipule as configurações de Bluetooth, declare a BLUETOOTH_ADMIN permissão. 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 modifica as configurações de Bluetooth mediante solicitação do usuário. Declare a permissão no arquivo de manifesto do app. 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 ACCESS_BACKGROUND_LOCATION permissão 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 <uses-permission> referência 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 <uses-feature> elemento permite especificar o tipo de hardware usado pelo app 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 o app depende do Bluetooth de baixa energia, use o seguinte:

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

Se você disser que o recurso é necessário para o 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 funcionar sem o recurso.

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

Para disponibilizar o app para dispositivos que não oferecem suporte ao Bluetooth clássico ou BLE, inclua o elemento <uses-feature> no manifesto do app, mas defina required="false". Em seguida, no momento da execução, você pode determinar a disponibilidade de recursos 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);