Bluetooth-Berechtigungen

Wenn Sie Bluetooth-Funktionen in Ihrer App verwenden möchten, müssen Sie mehrere Berechtigungen deklarieren. Sie sollten auch angeben, ob Ihre App Unterstützung für Bluetooth Classic oder Bluetooth Low Energy (BLE) erfordert. Wenn für Ihre App kein Bluetooth Classic oder BLE erforderlich ist, sie aber trotzdem von diesen Technologien profitieren kann, können Sie zur Laufzeit prüfen, ob sie verfügbar sind.

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 Ihre App auf Android 12 (API‑Level 31) oder höher ausgerichtet ist, deklarieren Sie die folgenden Berechtigungen in der Manifestdatei Ihrer App:

1. Wenn Ihre App nach Bluetooth-Geräten sucht, z. B. nach BLE-Peripheriegeräten, deklarieren Sie die Berechtigung BLUETOOTH_SCAN.
2. Wenn Ihre App das aktuelle Gerät für andere Bluetooth-Geräte sichtbar macht, deklarieren Sie die Berechtigung BLUETOOTH_ADVERTISE.
3. Wenn Ihre App mit bereits gekoppelten Bluetooth-Geräten kommuniziert, deklarieren Sie die Berechtigung BLUETOOTH_CONNECT.
4. Legen Sie für Ihre alten Bluetooth-Berechtigungserklärungen android:maxSdkVersion auf 30 fest. Dieser Schritt zur App-Kompatibilität hilft dem System, Ihrer App nur die Bluetooth-Berechtigungen zu erteilen, die sie benötigt, wenn sie auf Geräten mit Android 12 oder höher installiert wird.
5. Wenn Ihre App Bluetooth-Scanergebnisse verwendet, um den physischen Standort zu ermitteln, deklarieren Sie die Berechtigung ACCESS_FINE_LOCATION. Andernfalls können Sie nachdrücklich versichern, dass Ihre App keinen physischen Standort ableitet, und android:maxSdkVersion für die Berechtigung ACCESS_FINE_LOCATION auf 30 festlegen.

Die Berechtigungen BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT und BLUETOOTH_SCAN sind Laufzeitberechtigungen. Daher müssen Sie in Ihrer App explizit die Zustimmung des Nutzers einholen, 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 Sie Bluetooth-bezogene Berechtigungen in Ihrer App deklarieren, wenn sie für Android 12 oder höher entwickelt wurde:

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

Sie betonen nachdrücklich, dass Ihre App keine physischen Standorte ableitet.

Wenn Ihre App keine Bluetooth-Scanergebnisse verwendet, um den physischen Standort zu ermitteln, können Sie eine starke Behauptung aufstellen, dass Ihre App die Bluetooth-Berechtigungen niemals verwendet, um den physischen Standort zu ermitteln. Führen Sie dazu folgende Schritte aus:

1. Fügen Sie Ihrer BLUETOOTH_SCAN-Berechtigungserklärung das Attribut android:usesPermissionFlags 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>

Ausrichtung auf Android 11 oder niedriger

Wenn Ihre App auf Android 11 (API-Level 30) oder niedriger ausgerichtet ist, deklarieren Sie die folgenden Berechtigungen in der Manifestdatei Ihrer App:

• BLUETOOTH ist erforderlich, um Bluetooth Classic- oder BLE-Kommunikation durchzuführen, z. B. eine Verbindung anzufordern, eine Verbindung anzunehmen und Daten zu übertragen.
• 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 sie zur Laufzeit anfordern und gleichzeitig in Ihrem Manifest deklarieren.

Lokale Bluetooth-Geräte finden

Wenn Ihre App die Gerätesuche starten oder Bluetooth-Einstellungen bearbeiten soll, 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, wenn die App ein „Power Manager“ ist, der Bluetooth-Einstellungen auf Nutzeranfrage ändert. Deklarieren Sie die Berechtigung in der Manifestdatei Ihrer App. 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 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>.

Bluetooth-Funktionsnutzung 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 den Typ der Hardware angeben, die Ihre App verwendet, und 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 Ihre App auf Bluetooth Low Energy basiert, 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 Ihre App im Google Play Store für Nutzer auf Geräten ohne diese Funktionen ausgeblendet. Aus diesem Grund sollten Sie das Attribut „required“ nur auf true setzen, 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 Bluetooth Classic oder BLE nicht unterstützen, sollten Sie das Element <uses-feature> weiterhin in das Manifest Ihrer App aufnehmen, aber required="false" festlegen. Zur Laufzeit können Sie dann die Verfügbarkeit von Funktionen 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);