Uprawnienia Bluetooth

Aby korzystać z funkcji Bluetooth w aplikacji, musisz zadeklarować kilka uprawnień. Należy też określić, czy aplikacja wymaga obsługi klasycznego Bluetootha czy Bluetooth Low Energy (BLE). Jeśli aplikacja nie wymaga klasycznego Bluetootha ani BLE, ale może korzystać z tych technologii, możesz sprawdzić dostępność w czasie działania.

Deklarowanie uprawnień

Zestaw uprawnień, które deklarujesz w aplikacji, zależy od docelowej wersji pakietu SDK aplikacji.

Kierowanie na Androida 12 lub nowszego

Jeśli Twoja aplikacja jest kierowana na Androida 12 (API na poziomie 31) lub nowszego, zadeklaruj w pliku manifestu aplikacji te uprawnienia:

1. Jeśli aplikacja szuka urządzeń Bluetooth, takich jak urządzenia peryferyjne BLE, zadeklaruj uprawnienie BLUETOOTH_SCAN.
2. Jeśli aplikacja umożliwia wykrywanie bieżącego urządzenia przez inne urządzenia Bluetooth, zadeklaruj uprawnienie BLUETOOTH_ADVERTISE.
3. Jeśli aplikacja komunikuje się ze sparowanymi już urządzeniami Bluetooth, zadeklaruj uprawnienie BLUETOOTH_CONNECT.
4. W przypadku starszych deklaracji uprawnień związanych z Bluetoothem ustaw android:maxSdkVersion na 30. Ten krok dotyczący zgodności aplikacji pomaga systemowi przyznać aplikacji tylko te uprawnienia Bluetooth, których potrzebuje, gdy jest zainstalowana na urządzeniach z Androidem 12 lub nowszym.
5. Jeśli aplikacja używa wyników skanowania Bluetooth do określania lokalizacji fizycznej, zadeklaruj uprawnienie ACCESS_FINE_LOCATION. W przeciwnym razie możesz wyraźnie zadeklarować, że aplikacja nie pobiera lokalizacji fizycznej, i ustawić android:maxSdkVersion na 30 w przypadku uprawnienia ACCESS_FINE_LOCATION.

Uprawnienia BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT i BLUETOOTH_SCAN to uprawnienia w czasie działania aplikacji. Dlatego musisz wyraźnie poprosić użytkownika o zgodę w aplikacji, zanim będzie można wyszukiwać urządzenia Bluetooth, ustawić urządzenie jako wykrywalne dla innych urządzeń lub komunikować się ze sparowanymi już urządzeniami Bluetooth. Gdy aplikacja prosi o co najmniej jedno z tych uprawnień, system wyświetla użytkownikowi prośbę o zezwolenie aplikacji na dostęp do urządzeń w pobliżu, jak pokazano na rysunku 1.

Poniższy fragment kodu pokazuje, jak zadeklarować uprawnienia związane z Bluetoothem w aplikacji kierowanej na Androida 12 lub nowszego:

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

Zdecydowanie potwierdź, że aplikacja nie określa lokalizacji fizycznej

Jeśli aplikacja nie używa wyników skanowania Bluetooth do określania lokalizacji fizycznej, możesz złożyć oświadczenie, że aplikacja nigdy nie używa uprawnień Bluetooth do określania lokalizacji fizycznej. Aby to zrobić, wykonaj następujące czynności:

1. Dodaj atrybut android:usesPermissionFlags do deklaracji uprawnień BLUETOOTH_SCAN i ustaw wartość tego atrybutu na neverForLocation.

2. Jeśli lokalizacja nie jest potrzebna do działania aplikacji, usuń uprawnienie ACCESS_FINE_LOCATION z pliku manifestu aplikacji.

Poniższy fragment kodu pokazuje, jak zaktualizować plik manifestu aplikacji:

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

Kierowanie na Androida 11 lub starszego

Jeśli Twoja aplikacja jest kierowana na Androida 11 (poziom interfejsu API 30) lub starszego, zadeklaruj w pliku manifestu aplikacji te uprawnienia:

• Uprawnienie BLUETOOTH jest niezbędne do wykonywania wszelkich operacji komunikacyjnych przez klasyczny Bluetooth lub BLE, takich jak żądanie połączenia, akceptowanie połączenia i przesyłanie danych.
• ACCESS_FINE_LOCATION jest konieczne, ponieważ na Androidzie 11 i starszych wersjach skanowanie Bluetooth może być używane do zbierania informacji o lokalizacji użytkownika.

Dostęp do lokalizacji to uprawnienia w czasie działania aplikacji, dlatego musisz poprosić o nie w czasie działania aplikacji i zadeklarować je w pliku manifestu.

Wykrywanie lokalnych urządzeń Bluetooth

Jeśli chcesz, aby aplikacja inicjowała wykrywanie urządzeń lub zmieniała ustawienia Bluetooth, musisz zadeklarować uprawnienie BLUETOOTH_ADMIN. Większość aplikacji potrzebuje tego uprawnienia wyłącznie do wykrywania lokalnych urządzeń Bluetooth. Nie używaj innych funkcji, które daje to uprawnienie, chyba że aplikacja jest „menedżerem zasilania”, który modyfikuje ustawienia Bluetootha na żądanie użytkownika. Zadeklaruj uprawnienia w pliku manifestu aplikacji. Przykład:

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

Jeśli aplikacja obsługuje usługę i może działać na Androidzie 10 (poziom API 29) lub Androidzie 11, musisz też zadeklarować uprawnienie ACCESS_BACKGROUND_LOCATION, aby wykrywać urządzenia Bluetooth. Więcej informacji o tym wymaganiu znajdziesz w artykule o dostępie do lokalizacji w tle.

Poniższy fragment kodu pokazuje, jak zadeklarować uprawnienie ACCESS_BACKGROUND_LOCATION:

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

Więcej informacji o deklarowaniu uprawnień aplikacji znajdziesz w <uses-permission>.

Określanie użycia funkcji Bluetooth

Jeśli Bluetooth jest kluczowym elementem aplikacji, możesz dodać do pliku manifestu flagi wskazujące na to wymaganie. Element <uses-feature> pozwala określić typ sprzętu, którego używa aplikacja, oraz to, czy jest on wymagany.

Ten przykład pokazuje, jak wskazać, że aplikacja wymaga klasycznego Bluetootha.

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

Jeśli Twoja aplikacja korzysta z Bluetooth Low Energy, możesz użyć tych opcji:

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

Jeśli określisz, że funkcja jest wymagana przez aplikację, Sklep Google Play ukryje aplikację przed użytkownikami urządzeń, które nie mają tych funkcji. Z tego powodu atrybut required należy ustawić na true tylko wtedy, gdy aplikacja nie może działać bez danej funkcji.

Sprawdzanie dostępności funkcji w czasie działania

Aby aplikacja była dostępna na urządzeniach, które nie obsługują klasycznego Bluetootha ani BLE, nadal musisz uwzględnić element <uses-feature> w pliku manifestu aplikacji, ale ustawić required="false". Następnie w czasie działania możesz określić dostępność funkcji za pomocą PackageManager.hasSystemFeature():

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