Permissões do Bluetooth

Para usar recursos Bluetooth no seu app, é necessário declarar vários do Cloud Storage. Você também precisa especificar se o app exige suporte para Bluetooth clássico ou Bluetooth de baixa energia (BLE). Se as O app não exige o Bluetooth clássico ou BLE, mas ainda pode se beneficiar desses recursos tecnologias, verifique a disponibilidade no momento da execução.

Declarar permissões

O conjunto de permissões declarados no app depende do objetivo dele Versão do SDK.

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 o seguinte permissões no arquivo de manifesto do app:

1. Se seu aplicativo procurar por Bluetooth dispositivos, como periféricos de BLE, declare o BLUETOOTH_SCAN permissão.
2. Se o app tornar o dispositivo atual detectável por outro Bluetooth dispositivos, declarar o BLUETOOTH_ADVERTISE permissão.
3. Se o app se comunicar com o Bluetooth já pareado dispositivos, declare o 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 conceda ao app apenas as permissões de Bluetooth necessárias quando instalado no dispositivos com o Android 12 ou versões mais recentes.
5. Se o app usa os resultados da verificação por Bluetooth para determinar a localização física, declare as ACCESS_FINE_LOCATION permissão. Caso contrário, você pode declarar fortemente que seu aplicativo não deriva localização física.

As permissões BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT e BLUETOOTH_SCAN são permissões de execução. Portanto, você deve solicitar explicitamente ao usuário aprovação no app antes de procurar Dispositivos Bluetooth, tornar um dispositivo detectável para outros dispositivos ou se comunicar com dispositivos Bluetooth já pareados. Quando seu app solicita pelo menos um essas permissões, o sistema solicitará que o usuário permita que seu aplicativo 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

Caso seu aplicativo não use os resultados da busca por Bluetooth para obter a localização física, você pode fazer uma declaração forte de que seu aplicativo 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 uma versão anterior

Caso o app seja destinado ao Android 11 (nível 30 da API) ou versões anteriores, declare o seguinte permissões no arquivo de manifesto do app:

• BLUETOOTH é obrigató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 busca por Bluetooth poderiam ser usadas 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, solicite 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 este 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. 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 Android 11, também é necessário declarar a ACCESS_BACKGROUND_LOCATION permissão para descobrir dispositivos Bluetooth. Para mais informações sobre isso, requisito, consulte Acessar a localização na 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 o <uses-permission> referência para mais informações sobre a declaração de permissões do app.

Especificar o uso do recurso Bluetooth

Se o Bluetooth for essencial para o app, adicione flags ao manifesto que indica essa exigência. O O elemento <uses-feature> permite especificar o tipo de hardware que o aplicativo usa e se ele é obrigatórios.

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 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ê afirmar que o recurso é necessário para seu app, a Google Play Store ocultar 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". Depois, no ambiente de execução, é possível 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);