Autorizzazioni Bluetooth

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

Dichiara le autorizzazioni

L'insieme di autorizzazioni dichiarate nella tua app dipende dalla versione dell'SDK di destinazione dell'app.

Scegli come target Android 12 o versioni successive

Nota : su Android 8.0 (livello API 26) e versioni successive, Gestione dispositivi companion (CDM) offre un metodo più semplificato per la connessione ai dispositivi companion rispetto alle autorizzazioni descritte in questa sezione. Il sistema CDM fornisce un'interfaccia utente di accoppiamento per conto della tua app e non richiede le autorizzazioni di accesso alla posizione.

Se vuoi avere un maggiore controllo sull'esperienza di accoppiamento e connessione, utilizza le autorizzazioni descritte in questa sezione.

Finestra di dialogo autorizzazioni Bluetooth
Finestra di dialogo Autorizzazioni di sistema, in cui viene chiesto all'utente di concedere a un'app l'autorizzazione a rilevare, pubblicizzare e connettersi a dispositivi nelle vicinanze da parte dell'app.

Se la tua app ha come target Android 12 (livello API 31) o versioni successive, dichiara le seguenti 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 la tua app rende il dispositivo corrente rilevabile da altri dispositivi Bluetooth, dichiara l'autorizzazione BLUETOOTH_ADVERTISE.
  3. Se la tua app comunica con dispositivi Bluetooth già accoppiati, dichiara l'autorizzazione BLUETOOTH_CONNECT.
  4. Per le tue dichiarazioni delle autorizzazioni relative al Bluetooth precedenti, imposta android:maxSdkVersion su 30. Questo passaggio relativo alla compatibilità delle app consente al sistema di concedere alla tua app solo le autorizzazioni Bluetooth di cui ha bisogno quando è installata su dispositivi con Android 12 o versioni successive.
  5. Se la tua app utilizza i risultati della scansione Bluetooth per rilevare la posizione fisica, dichiara l'autorizzazione ACCESS_FINE_LOCATION. In caso contrario, puoi dire con certezza che la tua app non rileva la posizione fisica.

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, renderli rilevabili ad 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 all'app di accedere ai 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 è destinata ad 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 fermamente che la tua app non rileva la posizione fisica

Se la tua app non utilizza i risultati della scansione Bluetooth per rilevare la posizione fisica, puoi affermare con certezza che l'app non usa mai le autorizzazioni Bluetooth per rilevare la 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 è altrimenti 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 della tua 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 le seguenti autorizzazioni nel file manifest dell'app:

  • BLUETOOTH è necessario per eseguire qualsiasi comunicazione Bluetooth classica o BLE, ad esempio per richiedere una connessione, accettare una connessione e trasferire dati.
  • ACCESS_FINE_LOCATION è necessaria perché su Android 11 e versioni precedenti potrebbe essere utilizzata una scansione Bluetooth 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 oltre a dichiararle nel manifest.

Scoprire i dispositivi Bluetooth locali

Se vuoi che l'app avvii il rilevamento del dispositivo o gestisca le impostazioni Bluetooth, devi dichiarare l'autorizzazione BLUETOOTH_ADMIN. La maggior parte delle app ha bisogno di questa autorizzazione esclusivamente per poter 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. Ad 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 dichiarare anche l'autorizzazione ACCESS_BACKGROUND_LOCATION per rilevare i dispositivi Bluetooth. Per ulteriori informazioni su questo requisito, consulta 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>

Consulta il riferimento <uses-permission> 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 al file manifest dei flag 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 per la tua app è richiesto il Bluetooth Classic.

<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 funzionalità è necessaria per la tua app, il Google Play Store nasconderà la tua app agli utenti sui dispositivi privi di tali funzionalità. Per questo motivo, dovresti impostare l'attributo obbligatorio su true solo se la tua app non può funzionare senza la funzionalità.

Verifica la disponibilità delle funzionalità in fase di runtime

Per rendere la tua app disponibile su dispositivi che non supportano Bluetooth Classic o BLE, devi comunque includere l'elemento <uses-feature> nel file manifest dell'app, ma impostare required="false". Quindi, in fase di esecuzione, 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);