Uprawnienia Bluetooth

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

Deklarowanie uprawnień

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

Docelowa wersja Androida 12 lub nowszego

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

1. Jeśli Twoja aplikacja szuka urządzeń Bluetooth, takich jak urządzenia peryferyjne BLE, zadeklaruj uprawnienie BLUETOOTH_SCAN.
2. Jeśli aplikacja udostępnia bieżące urządzenie innym urządzeniom Bluetooth, zadeklaruj uprawnienie BLUETOOTH_ADVERTISE.
3. Jeśli Twoja aplikacja komunikuje się z już sparowanymi urządzeniami Bluetooth, zadeklaruj uprawnienie BLUETOOTH_CONNECT.
4. W przypadku starszych deklaracji uprawnień dotyczących Bluetootha ustaw android:maxSdkVersion na 30. Ten etap zgodności aplikacji pozwala systemowi na przyznanie aplikacji tylko tych uprawnień dotyczących Bluetootha, które są wymagane w przypadku instalacji na urządzeniach z Androidem 12 lub nowszym.
5. Jeśli Twoja aplikacja używa wyników skanowania Bluetooth do ustalania lokalizacji fizycznej, zadeklaruj uprawnienie ACCESS_FINE_LOCATION. W przeciwnym razie możesz zdecydowanie twierdzić, że aplikacja nie określa fizycznej lokalizacji.

Uprawnienia BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT i BLUETOOTH_SCAN to uprawnienia czasu działania. Dlatego aby móc szukać urządzeń Bluetooth, ustawić je jako wykrywalne dla innych urządzeń czy komunikować się z już sparowanymi urządzeniami Bluetooth, musisz poprosić użytkownika o zatwierdzenie w aplikacji. Gdy aplikacja poprosi o co najmniej 1 z tych uprawnień, system poprosi użytkownika o zezwolenie na dostęp do Urządzeń w pobliżu, jak widać na rysunku 1.

Ten fragment kodu pokazuje, jak zadeklarować uprawnienia związane z Bluetoothem w aplikacji, jeśli jest ona kierowana 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>

Stanowczo twierdź, że aplikacja nie określa lokalizacji fizycznej

Jeśli aplikacja nie używa wyników skanowania Bluetooth do ustalania lokalizacji fizycznej, możesz zagwarantować, że aplikacja nigdy nie używa uprawnień Bluetooth do określania lokalizacji fizycznej. Aby to zrobić:

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

2. Jeśli lokalizacja nie jest potrzebna w żaden inny sposób, usuń uprawnienie ACCESS_FINE_LOCATION z jej pliku manifestu.

Ten 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" />

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

Kieruj na Androida w wersji 11 lub starszej

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

• BLUETOOTH jest niezbędny do wykonywania wszelkich komunikacji przez Bluetooth (klasycznej) lub BLE, np. wysyłania żądań połączenia, akceptowania połączenia i przesyłania danych.
• Element ACCESS_FINE_LOCATION jest niezbędny, ponieważ na Androidzie 11 i starszych wersjach skanowanie Bluetooth mogłoby zostać użyte do zebrania informacji o lokalizacji użytkownika.

Ponieważ uprawnienia do lokalizacji to uprawnienia czasu działania, musisz poprosić o te uprawnienia w czasie działania oraz zadeklarować je w pliku manifestu.

Wykrywanie lokalnych urządzeń Bluetooth

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

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

Jeśli Twoja aplikacja obsługuje usługę i może działać na Androidzie 10 (poziom interfejsu API 29) lub Androidzie 11, musisz też zadeklarować uprawnienia ACCESS_BACKGROUND_LOCATION do wykrywania urządzeń Bluetooth. Więcej informacji o tym wymaganiu znajdziesz w sekcji Dostęp do lokalizacji w tle.

Ten 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 dokumentacji <uses-permission>.

Określanie użycia funkcji Bluetooth

Jeśli Bluetooth jest kluczowym elementem Twojej aplikacji, możesz dodać do pliku manifestu flagi informujące o tym wymaganiu. Element <uses-feature> pozwala określić typ sprzętu używanego przez aplikację oraz określić, czy jest on wymagany.

Ten przykład pokazuje, jak wskazać, że w przypadku Twojej aplikacji wymagany jest klasyczny Bluetooth.

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

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

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

Jeśli uważasz, że funkcja jest wymagana, Sklep Google Play ukryje aplikację przed użytkownikami na urządzeniach, które nie mają tych funkcji. Z tego względu ustawienie wymaganego atrybutu na true należy ustawić tylko wtedy, gdy aplikacja nie będzie działać bez tej funkcji.

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

Aby udostępnić aplikację na urządzeniach, które nie obsługują klasycznego Bluetootha lub BLE, musisz uwzględnić element <uses-feature> w manifeście aplikacji, ale ustaw required="false". Następnie w czasie działania możesz określić dostępność funkcji za pomocą polecenia 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);