Esta página foi traduzida pela API Cloud Translation.

Permissões do Bluetooth

Para usar recursos Bluetooth no seu app, é necessário declarar vários do Google Cloud. Você também deve especificar se o app exige compatível com o Bluetooth clássico ou o 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

Observação : no Android 8.0 (nível 26 da API) e versões mais recentes, a Complementar O Gerenciador de dispositivos (CDM) fornece um método mais simplificado de conexão dispositivos complementares, em comparação com as permissões descritas nesta seção. A 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.

Caixa de diálogo de permissões do Bluetooth — Caixa de diálogo de permissões do sistema, solicitando que o usuário conceder permissão a um app para descobrir, anunciar e se conectar a locais próximos dispositivos.

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:

Se seu aplicativo procurar por Bluetooth dispositivos, como periféricos de BLE, declare o BLUETOOTH_SCAN permissão.
Se o app tornar o dispositivo atual detectável por outro Bluetooth dispositivos, declarar o BLUETOOTH_ADVERTISE permissão.
Se o app se comunicar com o Bluetooth já pareado dispositivos, declare o BLUETOOTH_CONNECT permissão.
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.
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 a seguir demonstra como declarar chaves Bluetooth permissões 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

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:

Adicione o atributo android:usesPermissionFlags à declaração de permissão BLUETOOTH_SCAN e defina o valor dele como neverForLocation.

Observação: se você incluir neverForLocation em android:usesPermissionFlags, alguns sensores BLE serão filtrados dos resultados da verificação.
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.

Descubra dispositivos Bluetooth locais

Se você quiser que o app inicie a descoberta de dispositivos ou manipule o Bluetooth é necessário declarar o BLUETOOTH_ADMIN permissão. 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 requisito, consulte Acessar a localização na segundo plano.

O snippet de código abaixo mostra como declarar a ACCESS_BACKGROUND_LOCATION. permissão:

<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. A 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 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ê 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 isso, só defina o atributo obrigatório como true se o app não puder funcionar sem o recurso.

Verificar a disponibilidade do recurso no momento da execução

Para disponibilizar o app a dispositivos que não têm suporte ao Bluetooth clássico ou BLE, você ainda precisa incluir o elemento <uses-feature> no manifesto, mas definiu required="false". Depois, no ambiente de execução, é possível a disponibilidade de recursos 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);