Bluetooth-Berechtigungen

Wenn Sie Bluetooth-Funktionen in Ihrer App verwenden möchten, müssen Sie mehrere Berechtigungen deklarieren. Du solltest auch angeben, ob deine App Unterstützung für Bluetooth Classic oder Bluetooth Low Energy (BLE) benötigt. Wenn Ihre App kein Bluetooth Classic oder BLE benötigt, aber dennoch von diesen Technologien profitieren kann, können Sie die Verfügbarkeit zur Laufzeit prüfen.

Berechtigungen deklarieren

Die Berechtigungen, die Sie in Ihrer App deklarieren, hängen von der Ziel-SDK-Version Ihrer App ab.

Android 12 oder höher als Zielversion festlegen

Systemdialogfeld, in dem die Berechtigung für den Zugriff auf Geräte in der Nähe angefordert wird
Dialogfeld für Systemberechtigungen, in dem der Nutzer aufgefordert wird, einer App die Berechtigung zu erteilen, Geräte in der Nähe zu finden, zu bewerben und eine Verbindung zu ihnen herzustellen.

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

  1. Wenn deine App nach Bluetooth-Geräten sucht, z. B. BLE-Peripheriegeräten, deklariere die Berechtigung BLUETOOTH_SCAN.
  2. Wenn deine App das aktuelle Gerät für andere Bluetooth-Geräte sichtbar macht, deklariere die Berechtigung BLUETOOTH_ADVERTISE.
  3. Wenn deine App mit bereits gekoppelten Bluetooth-Geräten kommuniziert, deklariere die Berechtigung BLUETOOTH_CONNECT.
  4. Setze für deine alten Bluetooth-bezogenen Berechtigungserklärungen android:maxSdkVersion auf 30. Durch diesen Schritt zur App-Kompatibilität kann das System Ihrer App nur die Bluetooth-Berechtigungen gewähren, die sie benötigt, wenn sie auf Geräten mit Android 12 oder höher installiert ist.
  5. Wenn Ihre App Bluetooth-Scanergebnisse verwendet, um den physischen Standort zu ermitteln, deklarieren Sie die Berechtigung ACCESS_FINE_LOCATION. Andernfalls kannst du mit Nachdruck betonen, dass deine App den physischen Standort nicht ableitet, und android:maxSdkVersion für die Berechtigung ACCESS_FINE_LOCATION auf 30 setzen.

Die Berechtigungen BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT und BLUETOOTH_SCAN sind Laufzeitberechtigungen. Daher musst du in deiner App explizit die Genehmigung des Nutzers anfordern, bevor du nach Bluetooth-Geräten suchen, ein Gerät für andere Geräte sichtbar machen oder mit bereits gekoppelten Bluetooth-Geräten kommunizieren kannst. Wenn deine App mindestens eine dieser Berechtigungen anfordert, wird der Nutzer vom System aufgefordert, deiner App den Zugriff auf Geräte in der Nähe zu erlauben, wie in Abbildung 1 dargestellt.

Das folgende Code-Snippet zeigt, 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>

Nachdrücklich betonen, dass Ihre App den physischen Standort nicht ermittelt

Wenn deine App keine Bluetooth-Scanergebnisse verwendet, um den physischen Standort zu ermitteln, kannst du eine verbindliche Erklärung abgeben, dass deine App die Bluetooth-Berechtigungen nie verwendet, um den physischen Standort zu ermitteln. Führen Sie dazu folgende Schritte aus:

  1. Fügen Sie das Attribut android:usesPermissionFlags zur Erklärung zu Berechtigungen BLUETOOTH_SCAN hinzu und legen Sie den Wert dieses Attributs auf neverForLocation fest.

  2. Wenn der Standort für Ihre App nicht anderweitig benötigt wird, 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" />

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

Auf Android 11 oder niedriger ausgerichtet sind

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

  • BLUETOOTH ist für die Kommunikation über Bluetooth Classic oder BLE erforderlich, z. B. zum Anfordern einer Verbindung, zum Akzeptieren einer Verbindung und zum Übertragen von Daten.
  • ACCESS_FINE_LOCATION ist erforderlich, da unter Android 11 und niedriger ein Bluetooth-Scan potenziell verwendet werden könnte, um Informationen über den Standort des Nutzers zu erfassen.

Da Berechtigungen zur Standortermittlung Laufzeitberechtigungen sind, musst du sie zur Laufzeit anfordern und in deinem Manifest deklarieren.

Bluetooth-Geräte in der Nähe finden

Wenn deine App die Geräteerkennung initiieren oder Bluetooth-Einstellungen ändern soll, musst du die Berechtigung BLUETOOTH_ADMIN deklarieren. Die meisten Apps benötigen diese Berechtigung nur, um Bluetooth-Geräte in der Nähe zu finden. Verwende die anderen durch diese Berechtigung gewährten Funktionen nur, wenn die App ein „Power Manager“ ist, der die Bluetooth-Einstellungen auf Nutzeranfrage ändert. Deklariere die Berechtigung in der App-Manifestdatei deiner App. 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 deklarieren, um Bluetooth-Geräte zu finden. 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 zu <uses-permission>.

Nutzung von 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> kannst du den Typ der von deiner App verwendeten Hardware angeben und festlegen, ob sie erforderlich ist.

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

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

Wenn deine App Bluetooth Low Energy verwendet, kannst du Folgendes nutzen:

<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 sollten Sie das erforderliche Attribut nur dann auf true setzen, wenn Ihre App ohne die Funktion nicht funktioniert.

Verfügbarkeit von Funktionen 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 das Element <uses-feature> im Manifest deiner App angeben, aber required="false" festlegen. Anschließend können Sie zur Laufzeit die Verfügbarkeit von Funktionen mit PackageManager.hasSystemFeature() ermitteln:

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