Per utilizzare le funzionalità Bluetooth nella tua app, devi dichiarare diverse autorizzazioni. Devi anche specificare se la tua app richiede il supporto per Bluetooth classico o Bluetooth Low Energy (BLE). Se la tua app non richiede Bluetooth classico o BLE, ma può comunque trarre vantaggio da queste tecnologie, puoi verificare la disponibilità in fase di runtime.
Dichiarare le autorizzazioni
Il set di autorizzazioni che dichiari nella tua app dipende dalla versione dell'SDK di destinazione dell'app.
Target Android 12 o versioni successive
Nota : su Android 8.0 (livello API 26) e versioni successive, il Companion Device Manager (CDM) fornisce un metodo più semplice per connettersi ai dispositivi complementari, rispetto alle autorizzazioni descritte in questa sezione. Il sistema CDM fornisce un'interfaccia utente di accoppiamento per conto della tua app e non richiede autorizzazioni di accesso alla posizione.
Se vuoi avere un maggiore controllo sull'esperienza di accoppiamento e connessione, utilizza le autorizzazioni descritte in questa sezione.
Se la tua app ha come target Android 12 (livello API 31) o versioni successive, dichiara le seguenti autorizzazioni nel file manifest dell'app:
- Se la tua app cerca dispositivi Bluetooth, come periferiche BLE, dichiara l'autorizzazione
BLUETOOTH_SCAN
. - Se la tua app rende rilevabile il dispositivo attuale ad altri dispositivi Bluetooth,
dichiara l'autorizzazione
BLUETOOTH_ADVERTISE
. - Se la tua app comunica con dispositivi Bluetooth già accoppiati, dichiara l'autorizzazione
BLUETOOTH_CONNECT
. - Per le dichiarazioni di autorizzazione legacy relative al Bluetooth, imposta
android:maxSdkVersion
su 30. Questo passaggio di compatibilità dell'app consente al sistema di concedere alla tua app solo le autorizzazioni Bluetooth di cui ha bisogno quando viene installata su dispositivi con Android 12 o versioni successive. - Se la tua app utilizza i risultati della scansione Bluetooth per ricavare la posizione fisica, dichiara l'autorizzazione
ACCESS_FINE_LOCATION
. In caso contrario, puoi affermare con decisione che la tua app non ricava la posizione fisica e impostareandroid:maxSdkVersion
su 30 per l'autorizzazioneACCESS_FINE_LOCATION
.
Le autorizzazioni BLUETOOTH_ADVERTISE
, BLUETOOTH_CONNECT
e BLUETOOTH_SCAN
sono autorizzazioni di runtime.
Pertanto, devi richiedere esplicitamente l'approvazione dell'utente nella tua app prima di poter cercare dispositivi Bluetooth, rendere un dispositivo rilevabile da altri dispositivi o comunicare con dispositivi Bluetooth già accoppiati. Quando la tua app richiede almeno una di queste autorizzazioni, il sistema chiede all'utente di consentire alla tua app di accedere a Dispositivi nelle vicinanze, come mostrato nella Figura 1.
Il seguente snippet di codice mostra come dichiarare le autorizzazioni relative al Bluetooth nella tua app se ha come target Android 12 o versioni successive:
<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>
Afferma con decisione che la tua app non ricava la posizione fisica
Se la tua app non utilizza i risultati della scansione Bluetooth per ricavare la posizione fisica, puoi affermare con certezza che la tua app non utilizza mai le autorizzazioni Bluetooth per ricavare la posizione fisica. Per farlo, segui questi passaggi:
Aggiungi l'attributo
android:usesPermissionFlags
alla dichiarazione delle autorizzazioniBLUETOOTH_SCAN
e imposta il valore di questo attributo suneverForLocation
.Se la posizione non è necessaria per la tua app, rimuovi l'autorizzazione
ACCESS_FINE_LOCATION
dal file manifest dell'app.
Il seguente snippet di codice mostra come aggiornare il file manifest dell'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>
Target Android 11 o versioni precedenti
Se la tua app ha come target Android 11 (livello API 30) o versioni precedenti, dichiara le seguenti autorizzazioni nel file manifest dell'app:
BLUETOOTH
è necessario per eseguire qualsiasi comunicazione Bluetooth classica o BLE, ad esempio richiedere una connessione, accettare una connessione e trasferire dati.ACCESS_FINE_LOCATION
è necessaria perché su Android 11 e versioni precedenti, una scansione Bluetooth potrebbe essere utilizzata per raccogliere informazioni sulla posizione dell'utente.
Poiché le autorizzazioni di accesso alla posizione sono autorizzazioni di runtime, devi richiederle in fase di runtime e dichiararle nel manifest.
Rilevare i dispositivi Bluetooth locali
Se vuoi che la tua app avvii la ricerca di dispositivi o manipoli le impostazioni Bluetooth, devi dichiarare l'autorizzazione BLUETOOTH_ADMIN
. La maggior parte delle app ha bisogno di questa autorizzazione solo per rilevare
i dispositivi Bluetooth locali. Non utilizzare le altre funzionalità concesse da questa
autorizzazione a meno che l'app non sia un "gestore dell'alimentazione" che modifica le impostazioni Bluetooth
su richiesta dell'utente. Dichiara l'autorizzazione nel file manifest dell'app. Per
esempio:
<manifest>
...
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
...
</manifest>
Se la tua app supporta un servizio e può essere eseguita su Android 10 (livello API 29) o
Android 11, devi anche dichiarare l'autorizzazione
ACCESS_BACKGROUND_LOCATION
per rilevare i dispositivi Bluetooth. Per maggiori informazioni su questo
requisito, vedi Accedere alla posizione in
background.
Il seguente snippet di codice mostra come dichiarare l'autorizzazione ACCESS_BACKGROUND_LOCATION
:
<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
...
</manifest>
Per ulteriori informazioni sulla dichiarazione delle autorizzazioni app, consulta il riferimento <uses-permission>
.
Specificare l'utilizzo della funzionalità Bluetooth
Se il Bluetooth è un elemento fondamentale della tua app, puoi aggiungere flag al file manifest
che indicano questo requisito. L'elemento
<uses-feature>
ti consente
di specificare il tipo di hardware utilizzato dalla tua app e se è
obbligatorio o meno.
Questo esempio mostra come indicare che è richiesto il Bluetooth classico per la tua app.
<uses-feature android:name="android.hardware.bluetooth" android:required="true"/>
Se la tua app si basa su Bluetooth Low Energy, puoi utilizzare quanto segue:
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
Se indichi che la funzionalità è necessaria per la tua app, il Google Play Store
nasconderà la tua app agli utenti su dispositivi che non dispongono di queste funzionalità. Per questo motivo, devi impostare l'attributo richiesto su true
solo se la tua app non può funzionare senza la funzionalità.
Verificare la disponibilità delle funzionalità in fase di runtime
Per rendere la tua app disponibile per i dispositivi che non supportano Bluetooth classico o
BLE, devi comunque includere l'elemento <uses-feature>
nel
manifest dell'app, ma imposta required="false"
. Poi, in fase di runtime, puoi determinare
la disponibilità delle funzionalità utilizzando
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);