Para usar recursos do Bluetooth no app, é necessário declarar várias permissões. Você também precisa 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 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
como30
. 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. - Caso o app use resultados da verificação Bluetooth para receber 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, 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 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:
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" />
<!-- 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. 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 no momento da 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 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 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, 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 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 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);