Para usar recursos do Bluetooth no app, é necessário declarar várias permissões. Também é necessário 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 BLE, mas ainda puder se beneficiar dessas tecnologias, verifique a disponibilidade no momento da execução.
Declarar permissões
O conjunto de permissões declarados no app depende da versão do SDK de destino do app.
Segmentar o Android 12 ou mais recente
Observação : no Android 8.0 (nível 26 da API) e versões mais recentes, o Gerenciador de dispositivos complementar (CDM, na sigla em inglês) oferece um método mais simples de conexão com dispositivos complementares, em comparação com as permissões descritas nesta seção. O sistema CDM oferece 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 versões mais recentes, 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 Bluetooth necessárias quando instalado em dispositivos com o Android 12 ou versões mais recentes. - Se o app usa resultados da verificação Bluetooth para obter 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, é necessário solicitar a aprovação
do usuário explicitamente no seu 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 solicita pelo menos uma dessas
permissões, o sistema pede para 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 uma versão anterior
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 executar 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 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 durante a 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 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, você poderá adicionar flags ao arquivo
de manifesto indicando esse requisito. O elemento
<uses-feature>
permite
especificar o tipo de hardware que o app usa 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 seu app depende do Bluetooth de baixa energia, você pode usar o seguinte:
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
Se você informar que o recurso é necessário para seu 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 puder funcionar sem
o recurso.
Verificar a disponibilidade do recurso no momento da 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 ambiente 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);