Uprawnienia Bluetooth

Aby korzystać z funkcji Bluetootha w aplikacji, musisz zadeklarować kilka uprawnień. Musisz też określić, czy aplikacja wymaga obsługi Bluetootha klasycznego czy Bluetootha Low Energy (BLE). Jeśli Twoja aplikacja nie wymaga Bluetootha klasycznego 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.

kierować aplikację 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 wyszukuje urządzenia Bluetooth, takie jak urządzenia peryferyjne BLE, zadeklaruj uprawnienie BLUETOOTH_SCAN.
2. Jeśli aplikacja ustawia bieżące urządzenie jako wykrywalne dla innych urządzeń Bluetooth, zadeklaruj uprawnienie BLUETOOTH_ADVERTISE.
3. Jeśli aplikacja komunikuje się z urządzeniami Bluetooth, które są już sparowane, zadeklaruj uprawnienie BLUETOOTH_CONNECT.
4. W przypadku deklaracji uprawnień związanych ze starszą wersją Bluetootha ustaw wartość android:maxSdkVersion na 30. Ten krok dotyczący zgodności aplikacji pomaga systemowi przyznawać aplikacji tylko te uprawnienia Bluetooth, których potrzebuje po zainstalowaniu na urządzeniach z Androidem 12 lub nowszym.
5. Jeśli aplikacja używa wyników skanowania Bluetooth do określania fizycznej lokalizacji, zadeklaruj uprawnienie ACCESS_FINE_LOCATION. W przeciwnym razie możesz zdecydowanie oświadczyć, że Twoja aplikacja nie określa lokalizacji fizycznej i ustawić wartość 30 dla uprawnienia ACCESS_FINE_LOCATION.android:maxSdkVersion

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

Poniższy fragment kodu pokazuje, jak zadeklarować w aplikacji uprawnienia związane z Bluetooth, 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>

Zdecydowanie oświadcz, że Twoja aplikacja nie określa lokalizacji fizycznej

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

1. Dodaj atrybut android:usesPermissionFlags do BLUETOOTH_SCANdeklaracji uprawnień i ustaw jego wartość na neverForLocation.

2. Jeśli lokalizacja nie jest potrzebna w innych funkcjach 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>

kierować aplikację na Androida 11 lub starszego,

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

• BLUETOOTH jest niezbędne do komunikacji Bluetooth Classic lub BLE, np. do wysyłania prośby o połączenie, akceptowania połączenia i przesyłania danych.
• ACCESS_FINE_LOCATION jest niezbędne, ponieważ na Androidzie 11 i starszych wersjach skanowanie Bluetootha może być potencjalnie wykorzystywane do zbierania informacji o lokalizacji użytkownika.

Ponieważ uprawnienia do lokalizacji są uprawnieniami w czasie działania, musisz poprosić o nie w czasie działania i zadeklarować je w pliku manifestu.

Wykrywanie lokalnych urządzeń Bluetooth

Jeśli chcesz, aby aplikacja inicjowała wykrywanie urządzeń lub manipulowała ustawieniami Bluetootha, musisz zadeklarować uprawnienie BLUETOOTH_ADMIN. Większość aplikacji potrzebuje tego uprawnienia wyłącznie do wykrywania lokalnych urządzeń Bluetooth. Nie korzystaj z innych uprawnień przyznanych przez to uprawnienie, chyba że aplikacja jest „menedżerem zasilania”, który modyfikuje ustawienia Bluetooth na żądanie 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ć uprawnienie ACCESS_BACKGROUND_LOCATION do wykrywania urządzeń Bluetooth. Więcej informacji o tym wymaganiu znajdziesz w artykule 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 <uses-permission>dokumentacji.

Określanie użycia funkcji Bluetooth

Jeśli Bluetooth jest kluczowym elementem aplikacji, możesz dodać do pliku manifestu flagi wskazujące to wymaganie. Element <uses-feature> umożliwia określenie typu sprzętu używanego przez aplikację oraz tego, 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 funkcji:

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

Jeśli zadeklarujesz, że funkcja jest wymagana w aplikacji, Google Play ukryje ją przed użytkownikami urządzeń, które nie mają tych funkcji. Z tego powodu atrybut wymagany należy ustawić na true tylko wtedy, gdy aplikacja nie może 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ą Bluetootha w wersji klasycznej ani BLE, nadal musisz umieścić element <uses-feature> w manifeście aplikacji, ale ustawić required="false". Następnie w czasie działania możesz określić dostępność funkcji za pomocą metody 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);