Autorizzazioni Bluetooth

Per utilizzare le funzionalità Bluetooth nella tua app, devi dichiarare diverse autorizzazioni. Devi anche specificare se la tua app richiede Supporto per Bluetooth Classic o Bluetooth Low Energy (BLE). Se le tue non richiede Bluetooth Classic o BLE, ma può comunque trarre vantaggio da questi tecnologie, puoi verificare la disponibilità in fase di runtime.

Dichiarare le autorizzazioni

L'insieme di autorizzazioni che dichiari nella tua app dipende dal target dell'app Versione SDK.

Scegli come target Android 12 o versioni successive

Se la tua app ha come target Android 12 (livello API 31) o versioni successive, dichiara quanto segue autorizzazioni nel file manifest dell'app:

1. Se la tua app cerca dispositivi Bluetooth, ad esempio periferiche BLE, dichiara l'autorizzazione BLUETOOTH_SCAN.
2. Se l'app rende il dispositivo corrente rilevabile da altri dispositivi Bluetooth dispositivi mobili, dichiara il BLUETOOTH_ADVERTISE: autorizzazione.
3. Se la tua app comunica con il Bluetooth già associato dispositivi, dichiara BLUETOOTH_CONNECT: autorizzazione.
4. Per le dichiarazioni delle autorizzazioni relative al Bluetooth precedenti, imposta Da android:maxSdkVersion a 30. Questo passaggio relativo alla compatibilità delle app aiuta il sistema concedi alla tua app solo le autorizzazioni Bluetooth di cui ha bisogno quando è installata Dispositivi con Android 12 o versioni successive.
5. Se la tua app utilizza i risultati della scansione Bluetooth per rilevare la posizione fisica, dichiara il ACCESS_FINE_LOCATION autorizzazione. In caso contrario, puoi affermare chiaramente che la tua app non deriva località fisica.

Le autorizzazioni BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT e BLUETOOTH_SCAN sono autorizzazioni di runtime. Pertanto, devi richiedere esplicitamente all'utente approvazione nell'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 uno queste autorizzazioni, il sistema chiede all'utente di consentire alla tua app di accedere 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>

Affermare con chiarezza che la tua app non ricava la posizione fisica

Se la tua app non usa i risultati della scansione Bluetooth per rilevare la posizione fisica, affermare con certezza che la tua app non utilizza mai le autorizzazioni Bluetooth per risalire alla posizione fisica. Per farlo, segui questi passaggi:

1. Aggiungi l'attributo android:usesPermissionFlags alla dichiarazione delle autorizzazioni BLUETOOTH_SCAN e imposta il valore di questo attributo su neverForLocation.

2. Se la posizione non è necessaria per la tua app, rimuovi il 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" />

    <!-- 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>

Scegli come target Android 11 o versioni precedenti

Se la tua app ha come target Android 11 (livello API 30) o versioni precedenti, dichiara quanto segue autorizzazioni nel file manifest dell'app:

• Il campo BLUETOOTH è obbligatorio eseguire qualsiasi comunicazione Bluetooth Classic o BLE, ad esempio richiedere una connessione attiva, l'accettazione di una connessione e il trasferimento dei dati.
• ACCESS_FINE_LOCATION è necessaria perché, su Android 11 e versioni precedenti, una scansione Bluetooth potrebbe essere potenzialmente utilizzata per raccogliere informazioni sulla posizione dell'utente.

Poiché le autorizzazioni di accesso alla posizione sono autorizzazioni di runtime, devi richiedere queste autorizzazioni in fase di runtime insieme alla relativa dichiarazione nel file manifest.

Scopri dispositivi Bluetooth locali

Se vuoi che l'app avvii il rilevamento del dispositivo o manipola il Bluetooth devi dichiarare BLUETOOTH_ADMIN autorizzazione. La maggior parte delle app ha bisogno di questa autorizzazione solo per rilevare i dispositivi Bluetooth locali. Non usare le altre funzionalità concesse da questo a meno che l'app non sia "power manager" che modifica le impostazioni del 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) oppure Android 11, devi inoltre dichiarare ACCESS_BACKGROUND_LOCATION per rilevare i dispositivi Bluetooth. Per ulteriori informazioni consulta la sezione Accedere alla posizione nel lo sfondo.

Il seguente snippet di codice mostra come dichiarare l'autorizzazione ACCESS_BACKGROUND_LOCATION:

<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
...
</manifest>

Consulta la <uses-permission> riferimento per ulteriori informazioni sulla dichiarazione delle autorizzazioni app.

Specifica l'utilizzo delle funzionalità Bluetooth

Se il Bluetooth è un aspetto fondamentale della tua app, puoi aggiungere flag al file manifest che indica 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 è necessario il Bluetooth Classic per il tuo dell'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 dici che la funzione è obbligatoria per la tua app, il Google Play Store Nascondere l'app agli utenti sui dispositivi che non dispongono di queste funzionalità. Per questo motivo, imposta l'attributo obbligatorio su true solo se la tua app non può funzionare senza la caratteristica.

Verificare la disponibilità delle funzionalità in fase di runtime

Per rendere la tua app disponibile per i dispositivi che non supportano Bluetooth Classic o BLE, devi comunque includere l'elemento <uses-feature> nella ma imposta required="false". Poi, in fase di runtime, puoi determinare la disponibilità delle funzionalità utilizzando PackageManager.hasSystemFeature():

// 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)

// 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);