Uprawnienia Bluetooth

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

Deklarowanie uprawnień

Zestaw uprawnień zadeklarowanych w aplikacji zależy od docelowej wersji pakietu SDK.

kierować aplikację na Androida 12 lub nowszą wersję,

Uwaga: w Androidzie 8.0 (interfejs API na poziomie 26) i nowszych Menedżer urządzeń towarzyszących (CDM) zapewnia bardziej usprawniony sposób łączenia się z urządzeniami towarzyszącymi niż uprawnienia opisane w tej sekcji. System CDM udostępnia interfejs parowania w imieniu aplikacji i nie wymaga uprawnień do lokalizacji.

Jeśli chcesz mieć większą kontrolę nad parowaniem i łączeniem, użyj uprawnień opisanych w tej sekcji.

Okno uprawnień systemowych z prośbą o przyznanie aplikacji uprawnień do wykrywania, reklamowania i łączenia się z urządzeniami w pobliżu.

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

1. Jeśli aplikacja wyszukuje urządzeń Bluetooth, takich jak urządzenia peryferyjne BLE, zadeklaruj uprawnienie BLUETOOTH_SCAN.
2. Jeśli aplikacja czyni bieżące urządzenie wykrywalnym 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 starszych deklaracji uprawnień związanych z Bluetooth ustaw wartość android:maxSdkVersion na 30. Ten krok dotyczący zgodności aplikacji pomaga systemowi przyznać aplikacji tylko te uprawnienia Bluetooth, których potrzebuje po zainstalowaniu na urządzeniach z Androidem 12 lub nowszym.
5. Jeśli Twoja aplikacja korzysta z wyników skanowania Bluetooth, aby określić lokalizację fizyczną, zadeklaruj uprawnienie ACCESS_FINE_LOCATION. W przeciwnym razie możesz potwierdzić, że Twoja aplikacja nie określa fizycznej lokalizacji.

Uprawnienia BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT i BLUETOOTH_SCAN to uprawnienia czasu działania. Dlatego zanim zaczniesz wyszukiwać urządzenia Bluetooth, udostępniać urządzenie innym urządzeniom lub komunikować się z urządzeniami Bluetooth, które zostały już sparowane, musisz w aplikacji wyraźnie poprosić użytkownika o pozwolenie. Gdy aplikacja prosi o co najmniej 1 z tych uprawnień, system prosi użytkownika o zezwolenie na dostęp do Urządzeń w pobliżu, jak pokazano na rysunku 1.

Ten fragment kodu pokazuje, jak zadeklarować w aplikacji uprawnienia związane z Bluetooth, jeśli jest ona kierowana na Androida 12 lub nowszą wersję:

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

Potwierdź, że Twoja aplikacja nie określa fizycznej lokalizacji

Jeśli Twoja aplikacja nie korzysta z wyników skanowania Bluetooth do określenia lokalizacji fizycznej, możesz zdecydowanie stwierdzić, że nigdy nie korzysta z uprawnień Bluetooth do określenia lokalizacji fizycznej. Aby to zrobić:

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

   Uwaga: jeśli w pliku android:usesPermissionFlags uwzględnisz neverForLocation, niektóre beacony BLE zostaną odfiltrowane z wyników skanowania.

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

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>

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 wymagany do wykonywania komunikacji w Bluetooth klasycznym lub BLE, takiej jak żądanie połączenia, akceptacja połączenia i przesyłanie danych.
• ACCESS_FINE_LOCATIONjest konieczne, ponieważ w Androidzie 11 i starszych wersjach skanowanie Bluetootha może być wykorzystywane do zbierania informacji o lokalizacji użytkownika.

Uwaga: na urządzeniach z Androidem 8.0 lub nowszym możesz użyć funkcji CompanionDeviceManager, aby skanować urządzenia towarzyszące w pobliżu w imieniu aplikacji bez konieczności uzyskiwania uprawnień do lokalizacji. Więcej informacji o tej opcji znajdziesz w artykule Parowanie urządzenia towarzyszącego.

Ponieważ uprawnienia do lokalizacji są uprawnieniami w czasie 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 manipulowała ustawieniami Bluetootha, musisz zadeklarować uprawnienie BLUETOOTH_ADMIN. Większość aplikacji potrzebuje tego uprawnienia tylko do wykrywania lokalnych urządzeń Bluetooth. Nie używaj innych możliwości 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 dokumentacji <uses-permission>.

Określ użycie funkcji Bluetooth

Jeśli Bluetooth jest kluczowym elementem aplikacji, możesz dodać do pliku manifestu flagi wskazujące ten wymóg. Element <uses-feature> umożliwia określenie typu sprzętu używanego przez aplikację oraz wskazanie, czy jest on wymagany.

Ten przykład pokazuje, jak wskazać, że w aplikacji wymagana jest klasyczna technologia Bluetooth.

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

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

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

Jeśli oświadczysz, że dana funkcja jest wymagana w Twojej aplikacji, Sklep Google Play ukryje ją przed użytkownikami na urządzeniach, które nie mają tych funkcji. Z tego powodu atrybut required powinien mieć wartość true tylko wtedy, gdy aplikacja nie może działać bez tej funkcji.

Sprawdzanie dostępności funkcji w czasie wykonywania

Aby udostępnić aplikację na urządzeniach, które nie obsługują klasycznego Bluetootha ani BLE, nadal należy uwzględnić element <uses-feature> w pliku manifestu aplikacji, ale ustawić wartość required="false". Następnie w czasie wykonywania możesz określić dostępność funkcji, korzystając z funkcji PackageManager.hasSystemFeature():

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