Bluetooth-Berechtigungen

Wenn du Bluetooth-Funktionen in deiner App verwenden möchtest, musst du mehrere Berechtigungen deklarieren. Außerdem solltest du angeben, ob deine App Unterstützung für Bluetooth Classic oder Bluetooth Low Energy (BLE) benötigt. Wenn deine App kein Bluetooth Classic oder BLE benötigt, aber dennoch von diesen Technologien profitieren kann, kannst du 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.

Auf Android 12 oder höher ausrichten

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 Ihre App nach Bluetooth-Geräten sucht, z. B. BLE-Peripheriegeräten, deklarieren Sie 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 ausdrücklich erklären, 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 ableitet

Wenn deine App keine Bluetooth-Scanergebnisse verwendet, um den physischen Standort zu ermitteln, kannst du mit Nachdruck erklären, 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 möglicherweise 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.

Bluetooth-Geräte in der Nähe finden

Wenn deine App die Gerätesuche initiieren oder Bluetooth-Einstellungen ändern soll, musst du die Berechtigung BLUETOOTH_ADMIN deklarieren. Die meisten Apps benötigen diese Berechtigung nur, um lokale Bluetooth-Geräte zu finden. Verwenden Sie die anderen Funktionen, die durch diese Berechtigung gewährt werden, nur, wenn die App ein „Power Manager“ ist, der die Bluetooth-Einstellungen auf Nutzeranfrage ändert. Deklarieren Sie die Berechtigung in der App-Manifestdatei. Beispiel:

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

Wenn Ihre App einen Dienst unterstützt und unter 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 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 deiner App ist, kannst du deiner Manifestdatei Flags hinzufügen, die diese Anforderung angeben. Mit dem Element <uses-feature> kannst du den von deiner App verwendeten Hardwaretyp angeben und festlegen, ob er 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> trotzdem in das Manifest deiner App aufnehmen, aber required="false" festlegen. Anschließend können Sie die Verfügbarkeit von Funktionen zur Laufzeit mit PackageManager.hasSystemFeature() 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);