Bluetooth-Berechtigungen

Damit Sie Bluetooth-Funktionen in Ihrer App verwenden können, müssen Sie mehrere Berechtigungen deklarieren. Außerdem sollten Sie angeben, ob Ihre App Bluetooth Classic oder Bluetooth Low Energy (BLE) unterstützt. Wenn Ihre App kein Bluetooth Classic oder BLE erfordert, aber dennoch von diesen Technologien profitieren kann, können Sie die Verfügbarkeit zur Laufzeit prüfen.

Deklarieren von Berechtigungen

Welche Berechtigungen Sie in Ihrer App angeben, hängt von der SDK-Zielversion der App ab.

Ausrichtung auf Android 12 oder höher

Wenn deine App auf Android 12 (API-Level 31) oder höher ausgerichtet ist, gib in der Manifestdatei deiner App die folgenden Berechtigungen an:

1. Wenn Ihre App nach Bluetooth-Geräten wie BLE-Peripheriegeräten sucht, müssen Sie die Berechtigung BLUETOOTH_SCAN deklarieren.
2. Wenn Ihre App das aktuelle Gerät für andere Bluetooth-Geräte sichtbar macht, deklarieren Sie die Berechtigung BLUETOOTH_ADVERTISE.
3. Wenn deine App mit bereits gekoppelten Bluetooth-Geräten kommuniziert, musst du die Berechtigung BLUETOOTH_CONNECT deklarieren.
4. Legen Sie für die alten Deklarationen zu Bluetooth-Berechtigungen android:maxSdkVersion auf 30 fest. Mit diesem Schritt zur App-Kompatibilität kann das System deiner App nur die Bluetooth-Berechtigungen gewähren, die für die Installation auf Geräten mit Android 12 oder höher erforderlich sind.
5. Wenn Ihre App den physischen Standort mithilfe von Bluetooth-Scanergebnissen ableitet, erklären Sie die Berechtigung ACCESS_FINE_LOCATION. Andernfalls können Sie mit hoher Sicherheit behaupten, dass Ihre Anwendung keinen physischen Standort ableitet.

Die Berechtigungen BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT und BLUETOOTH_SCAN sind Laufzeitberechtigungen. Daher müssen Sie in Ihrer App explizit die Nutzergenehmigung anfordern, bevor Sie nach Bluetooth-Geräten suchen, ein Gerät für andere Geräte sichtbar machen oder mit bereits gekoppelten Bluetooth-Geräten kommunizieren können. Wenn Ihre App mindestens eine dieser Berechtigungen anfordert, fordert das System den Nutzer auf, Ihrer App den Zugriff auf Geräte in der Nähe zu erlauben (siehe Abbildung 1).

Das folgende Code-Snippet zeigt, wie Bluetooth-Berechtigungen in Ihrer App deklariert werden, wenn sie auf Android 12 oder höher ausgerichtet ist:

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

Bekräftigen Sie eindeutig, dass Ihre App keinen physischen Standort ableitet

Wenn Ihre App keine Bluetooth-Scanergebnisse verwendet, um den physischen Standort abzuleiten, können Sie mit hoher Sicherheit behaupten, dass Ihre App nie die Bluetooth-Berechtigungen zur Ermittlung des physischen Standorts verwendet. Führen Sie dazu die folgenden Schritte aus:

1. Fügen Sie Ihrer Berechtigungsdeklaration BLUETOOTH_SCAN das Attribut android:usesPermissionFlags hinzu und legen Sie den Wert dieses Attributs auf neverForLocation fest.

2. Wenn der Standort für deine App nicht anderweitig benötigt wird, entferne die Berechtigung ACCESS_FINE_LOCATION aus dem Manifest deiner App.

Das folgende Code-Snippet zeigt, wie Sie die Manifestdatei Ihrer App aktualisieren:

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

Ausrichtung auf Android 11 oder niedriger

Wenn deine App auf Android 11 (API-Level 30) oder niedriger ausgerichtet ist, gib in der Manifestdatei deiner App die folgenden Berechtigungen an:

• BLUETOOTH ist für die klassische oder BLE-Kommunikation erforderlich, z. B. für die Anforderung einer Verbindung, die Annahme einer Verbindung und die Übertragung von Daten.
• ACCESS_FINE_LOCATION ist erforderlich, da unter Android 11 und niedriger möglicherweise ein Bluetooth-Scan verwendet werden kann, um Informationen zum Standort des Nutzers zu erfassen.

Da Berechtigungen zur Standortermittlung Laufzeitberechtigungen sind, müssen Sie diese Berechtigungen zur Laufzeit anfordern und sie in Ihrem Manifest deklarieren.

Lokale Bluetooth-Geräte erkennen

Wenn Sie möchten, dass Ihre App die Geräteerkennung auslöst oder die Bluetooth-Einstellungen ändert, müssen Sie die Berechtigung BLUETOOTH_ADMIN deklarieren. Die meisten Apps benötigen diese Berechtigung nur, um lokale Bluetooth-Geräte zu erkennen. Verwenden Sie die anderen durch diese Berechtigung gewährten Funktionen nur dann, wenn die App ein „Power Manager“ ist, der die Bluetooth-Einstellungen auf Anfrage des Nutzers ändert. Deklariere die Berechtigung in deiner App-Manifestdatei. Beispiel:

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

Wenn deine App einen Dienst unterstützt und unter Android 10 (API-Level 29) oder Android 11 ausgeführt werden kann, musst du auch die Berechtigung ACCESS_BACKGROUND_LOCATION zum Erkennen von Bluetooth-Geräten deklarieren. Weitere Informationen zu dieser Anforderung finden Sie unter Im Hintergrund auf die Standortermittlung zugreifen.

Das folgende Code-Snippet zeigt, wie die Berechtigung ACCESS_BACKGROUND_LOCATION deklariert wird:

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

Weitere Informationen zum Deklarieren von App-Berechtigungen finden Sie in der Referenz zu <uses-permission>.

Nutzung der Bluetooth-Funktion festlegen

Wenn Bluetooth ein wichtiger Bestandteil deiner App ist, kannst du deiner Manifestdatei Flags hinzufügen, die diese Anforderung angeben. Mit dem Element <uses-feature> können Sie angeben, welche Art von Hardware Ihre App verwendet und ob diese erforderlich ist.

In diesem Beispiel wird gezeigt, wie du angeben kannst, dass Bluetooth Classic für deine App erforderlich ist.

<uses-feature android:name="android.hardware.bluetooth" android:required="true"/>

Wenn für Ihre App Bluetooth Low Energy erforderlich ist, können Sie Folgendes verwenden:

<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>

Wenn du angibst, dass die Funktion für deine App erforderlich ist, wird deine App im Google Play Store für Nutzer auf Geräten ohne diese Funktionen ausgeblendet. Aus diesem Grund solltest du das erforderliche Attribut nur auf true setzen, wenn deine App nicht ohne die Funktion funktioniert.

Verfügbarkeit von Features zur Laufzeit prüfen

Wenn du deine App für Geräte verfügbar machen möchtest, die Bluetooth Classic oder BLE nicht unterstützen, solltest du trotzdem das <uses-feature>-Element in das Manifest deiner App aufnehmen und dabei required="false" festlegen. Während der Laufzeit können Sie die Verfügbarkeit der Features mit PackageManager.hasSystemFeature() bestimmen:

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