Para usar os recursos de 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
Observação : no Android 8.0 (nível 26 da API) e versões mais recentes, o Gerenciador de dispositivos complementares (CDM, na sigla em inglês) oferece um método mais simplificado 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.
Se você quiser ter mais controle sobre a experiência de pareamento e conexão, use as permissões descritas nesta seção.
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:
- Se o app procurar dispositivos
Bluetooth, como
periféricos BLE, declare a
permissão
BLUETOOTH_SCAN
. - Se o app tornar o dispositivo atual detectável para outros dispositivos
Bluetooth,
declare a
permissão
BLUETOOTH_ADVERTISE
. - Se o app se comunicar com dispositivos Bluetooth
já pareados, declare a
permissão
BLUETOOTH_CONNECT
. - 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. - 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, declare explicitamente que o app não determina a localização física e definaandroid:maxSdkVersion
como 30 para a permissãoACCESS_FINE_LOCATION
.
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 para poder 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
os 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:
Adicione o atributo
android:usesPermissionFlags
à declaração de permissãoBLUETOOTH_SCAN
e defina o valor dele comoneverForLocation
.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 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 Bluetooth classic ou BLE, como solicitar uma conexão, aceitar uma conexão e transferir dados. - O
ACCESS_FINE_LOCATION
é necessário porque, no Android 11 e versões anteriores, uma verificação de 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 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 detectar
dispositivos Bluetooth locais. Não use as outras capacidades concedidas por essa
permissão, a menos que o app seja um "gerenciador de energia" que modifique as configurações do Bluetooth
quando solicitado pelo 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 detectar 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
que você especifique 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 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
BLE, ainda é 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()
:
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);