Bluetooth-Berechtigungen

Wenn du Bluetooth-Funktionen in deiner App verwenden möchtest, musst du mehrere Berechtigungen deklarieren. Du solltest außerdem angeben, ob deine App Unterstützung für klassisches Bluetooth oder Bluetooth Low Energy (BLE) benötigt. Wenn für Ihre App kein klassisches Bluetooth oder BLE erforderlich ist, Sie aber dennoch von diesen Technologien profitieren können, können Sie die Verfügbarkeit zur Laufzeit prüfen.

Erklärung von Berechtigungen

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

Ausrichtung auf Android 12 oder höher

Wenn Ihre App auf Android 12 (API-Level 31) oder höher ausgerichtet ist, müssen Sie in der Manifestdatei Ihrer App die folgenden Berechtigungen deklarieren:

1. Wenn Ihre App nach Bluetooth-Geräten wie BLE-Peripheriegeräten sucht, deklarieren Sie die Berechtigung BLUETOOTH_SCAN.
2. Wenn Ihre App das aktuelle Gerät für andere Bluetooth-Geräte sichtbar macht, müssen Sie die Berechtigung BLUETOOTH_ADVERTISE angeben.
3. Wenn Ihre App mit bereits gekoppelten Bluetooth-Geräten kommuniziert, müssen Sie die Berechtigung BLUETOOTH_CONNECT angeben.
4. Legen Sie für Ihre bisherigen Bluetooth-bezogenen Berechtigungserklärungen android:maxSdkVersion auf 30 fest. Mit diesem Schritt zur App-Kompatibilität kann das System Ihrer 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 Bluetooth-Scanergebnisse verwendet, um den physischen Standort zu ermitteln, erklären Sie die Berechtigung ACCESS_FINE_LOCATION. Andernfalls können Sie unsicher behaupten, dass Ihre Anwendung den physischen Standort nicht ermittelt.

Die Berechtigungen BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT und BLUETOOTH_SCAN sind Laufzeitberechtigungen. Daher müssen Sie in Ihrer App ausdrücklich die Genehmigung der Nutzer 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, wird der Nutzer aufgefordert, Ihrer App den Zugriff auf Geräte in der Nähe zu erlauben, wie in Abbildung 1 dargestellt.

Im folgenden Code-Snippet wird gezeigt, wie Sie Bluetooth-bezogene Berechtigungen in Ihrer App deklarieren, 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>

Bestreiten Sie ausdrücklich, dass Ihre App den physischen Standort ermittelt

Wenn Ihre App keine Bluetooth-Scanergebnisse verwendet, um den physischen Standort zu ermitteln, können Sie mit hoher Wahrscheinlichkeit angeben, dass Ihre App die Bluetooth-Berechtigungen nie verwendet, um den physischen Standort zu ermitteln. Führen Sie dazu die folgenden Schritte aus:

1. Fügen Sie der BLUETOOTH_SCAN-Berechtigungserklärung das Attribut android:usesPermissionFlags hinzu und legen Sie den Wert dieses Attributs auf neverForLocation fest.

2. Wenn die Standortermittlung für Ihre App nicht anderweitig erforderlich ist, entfernen Sie die Berechtigung ACCESS_FINE_LOCATION aus dem Manifest Ihrer 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 Ihre App auf Android 11 (API-Level 30) oder niedriger ausgerichtet ist, müssen Sie in der Manifestdatei Ihrer App die folgenden Berechtigungen deklarieren:

• BLUETOOTH ist für jede Bluetooth Classic- oder BLE-Kommunikation erforderlich, z. B. für das Anfordern, Akzeptieren und Übertragen von Verbindungen.
• ACCESS_FINE_LOCATION ist erforderlich, da unter Android 11 und niedriger ein Bluetooth-Scan potenziell dazu verwendet werden kann, 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 finden

Wenn deine App die Geräteerkennung initiieren oder die Bluetooth-Einstellungen ändern soll, musst du die Berechtigung BLUETOOTH_ADMIN erklären. Die meisten Apps benötigen diese Berechtigung nur, um lokale Bluetooth-Geräte erkennen zu können. Verwenden Sie die anderen durch diese Berechtigung gewährten Funktionen nur, wenn es sich bei der App um eine Energieverwaltung handelt, die die Bluetooth-Einstellungen auf Nutzeranfrage ändert. Deklariere die Berechtigung in der Manifestdatei deiner App. Beispiel:

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

Wenn Ihre App einen Dienst unterstützt und auf Android 10 (API-Level 29) oder Android 11 ausgeführt werden kann, müssen Sie auch die Berechtigung ACCESS_BACKGROUND_LOCATION deklarieren, um Bluetooth-Geräte zu erkennen. Weitere Informationen zu dieser Anforderung finden Sie unter Im Hintergrund auf den Standort 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 <uses-permission>.

Verwendung der Bluetooth-Funktionen angeben

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

In diesem Beispiel wird gezeigt, wie Sie angeben, dass für Ihre App Bluetooth Classic erforderlich ist.

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

Wenn Ihre App Bluetooth Low Energy nutzt, können Sie Folgendes verwenden:

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

Wenn Sie angeben, dass die Funktion für Ihre App erforderlich ist, wird sie im Google Play Store für Nutzer auf Geräten ausgeblendet, auf denen diese Funktionen nicht vorhanden sind. Daher sollten Sie das erforderliche Attribut nur dann auf true festlegen, wenn Ihre App ohne die Funktion nicht funktioniert.

Verfügbarkeit von Funktionen zur Laufzeit prüfen

Wenn Sie Ihre App für Geräte verfügbar machen möchten, die weder Bluetooth Classic noch BLE unterstützen, sollten Sie das Element <uses-feature> weiterhin in das Manifest Ihrer App aufnehmen, aber required="false" festlegen. Dann können Sie die Verfügbarkeit von Funktionen mithilfe von PackageManager.hasSystemFeature() während der Laufzeit ermitteln:

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