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 Ihre App Bluetooth Classic oder BLE nicht erfordert, aber dennoch von diesen Technologien profitieren kann, können Sie die Verfügbarkeit während der Laufzeit prüfen.
Erklärung von Berechtigungen
Welche Berechtigungen du in deiner App deklarierst, hängt von der SDK-Zielversion der App ab.
Auf Android 12 oder höher ausrichten
Hinweis : Unter Android 8.0 (API-Level 26) und höher bietet der Companion Device Manager (CDM) im Vergleich zu den in diesem Abschnitt beschriebenen Berechtigungen eine optimierte Methode, um eine Verbindung zu Begleitgeräten herzustellen. Das CDM-System bietet eine UI zum Koppeln im Namen deiner App und benötigt keine Berechtigungen zur Standortermittlung.
Wenn Sie das Koppeln und Verbinden genauer steuern möchten, verwenden Sie die in diesem Abschnitt beschriebenen Berechtigungen.
Wenn deine App auf Android 12 (API-Level 31) oder höher ausgerichtet ist, musst du in der Manifestdatei deiner App die folgenden Berechtigungen deklarieren:
- Wenn Ihre App nach Bluetooth-Geräten wie BLE-Peripheriegeräten sucht, deklarieren Sie die Berechtigung
BLUETOOTH_SCAN
. - Wenn deine App das aktuelle Gerät für andere Bluetooth-Geräte sichtbar macht, erkläre die Berechtigung
BLUETOOTH_ADVERTISE
. - Deklariere die Berechtigung
BLUETOOTH_CONNECT
, wenn deine App mit bereits gekoppelten Bluetooth-Geräten kommuniziert. - Legen Sie für Ihre alten Bluetooth-bezogenen Berechtigungsdeklarationen
android:maxSdkVersion
auf30
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. - Wenn Ihre App den physischen Standort anhand von Bluetooth-Suchergebnissen ermittelt, erklären Sie die Berechtigung
ACCESS_FINE_LOCATION
. Andernfalls können Sie endlich versichern, 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 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 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 gestatten (siehe Abbildung 1).
Das folgende Code-Snippet zeigt, wie Bluetooth-bezogene Berechtigungen in deiner 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>
Behaupten Sie deutlich, dass Ihre App keinen physischen Standort ermittelt.
Wenn Ihre App keine Bluetooth-Scanergebnisse zur Ermittlung des physischen Standorts verwendet, können Sie deutlich machen, dass Ihre App nie die Bluetooth-Berechtigungen zur Ermittlung des physischen Standorts verwendet. Führen Sie dazu die folgenden Schritte aus:
Fügen Sie der Erklärung zur Berechtigung
BLUETOOTH_SCAN
das Attributandroid:usesPermissionFlags
hinzu und legen Sie den Wert dieses Attributs aufneverForLocation
fest.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>
Auf Android 11 oder niedriger ausrichten
Wenn deine App auf Android 11 (API-Level 30) oder niedriger ausgerichtet ist, musst du in der Manifestdatei deiner App die folgenden Berechtigungen deklarieren:
BLUETOOTH
ist für die Kommunikation über Bluetooth Classic oder BLE erforderlich, z. B. für das Anfordern einer Verbindung, das Annehmen einer Verbindung und das Übertragen von Daten.ACCESS_FINE_LOCATION
ist erforderlich, da unter Android 11 und niedriger ein Bluetooth-Scan potenziell zur Erfassung von Informationen zum Standort des Nutzers verwendet werden könnte.
Da Berechtigungen zur Standortermittlung Laufzeitberechtigungen sind, müssen Sie diese Berechtigungen zur Laufzeit anfordern und in Ihrem Manifest deklarieren.
Bluetooth-Geräte in der Nähe 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 ausschließlich für die Fähigkeit, lokale Bluetooth-Geräte zu erkennen. Verwenden Sie die anderen durch diese Berechtigung gewährten Funktionen nur, wenn die App ein „Power Manager“ ist, der die Bluetooth-Einstellungen auf Nutzeranfrage hin ändert. Deklariere die Berechtigung in der 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 zum Erkennen von Bluetooth-Geräten auch die Berechtigung ACCESS_BACKGROUND_LOCATION
deklarieren. Weitere Informationen zu dieser Anforderung finden Sie unter Zugriff auf Standort im Hintergrund.
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 findest du in der Referenz zu <uses-permission>
.
Nutzung der Bluetooth-Funktion angeben
Wenn Bluetooth ein wichtiger Bestandteil deiner App ist, kannst du deiner Manifestdatei Flags hinzufügen, um auf diese Anforderung hinzuweisen. Mit dem Element <uses-feature>
können Sie angeben, welche Art von Hardware Ihre Anwendung verwendet und ob dies erforderlich ist.
In diesem Beispiel wird gezeigt, wie du angibst, dass Bluetooth Classic für deine App erforderlich ist.
<uses-feature android:name="android.hardware.bluetooth" android:required="true"/>
Wenn Ihre App Bluetooth Low Energy verwendet, 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 sie im Google Play Store für Nutzer von Geräten ohne diese Funktionen ausgeblendet. Daher solltest du das erforderliche Attribut nur auf true
setzen, wenn deine App ohne diese Funktion nicht funktioniert.
Verfügbarkeit von Funktionen während der 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 Element <uses-feature>
in das Manifest deiner App aufnehmen, aber required="false"
festlegen. Anschließend können Sie die Verfügbarkeit der Features während der Laufzeit 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);