Uprawnienia Bluetooth

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

Deklarowanie uprawnień

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

Kierowanie na Androida 12 lub nowszego

Uwaga: w Androidzie 8.0 (poziom interfejsu API 26) i nowszych Menedżer urządzeń towarzyszących (CDM) zapewnia łatwiejszy sposób łączenia się z urządzeniami towarzyszącymi od uprawnień opisanych w tej sekcji. System CDM udostępnia interfejs parowania w imieniu Twojej aplikacji i nie wymaga uprawnień do lokalizacji.

Jeśli chcesz mieć większą kontrolę nad procesem parowania i łączenia, skorzystaj z uprawnień opisanych w tej sekcji.

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

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

1. Jeśli aplikacja szuka urządzeń Bluetooth, np. urządzeń peryferyjnych BLE, zadeklaruj uprawnienie BLUETOOTH_SCAN.
2. Jeśli aplikacja umożliwia wykrywanie bieżącego urządzenia dla innych urządzeń 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ń związanych z Bluetoothem ustaw android:maxSdkVersion na 30. Ten krok dotyczący zgodności aplikacji pomaga systemowi przyznać aplikacji tylko te uprawnienia dotyczące Bluetootha, których potrzebuje, gdy jest zainstalowana na urządzeniach z Androidem 12 lub nowszym.
5. Jeśli aplikacja określa lokalizację fizyczną, korzystając z wyników skanowania Bluetooth, zadeklaruj uprawnienie ACCESS_FINE_LOCATION. W przeciwnym razie możesz zdecydowanie potwierdzić, że aplikacja nie określa lokalizacji fizycznej.

Uprawnienia BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT i BLUETOOTH_SCAN to uprawnienia czasu działania. Dlatego zanim będzie można wyszukać urządzenia Bluetooth, ustawić je jako wykrywalne dla innych urządzeń lub komunikować się z już sparowanymi urządzeniami Bluetooth, musisz wyraźnie poprosić o zatwierdzenie użytkownika w aplikacji. Gdy aplikacja prosi o co najmniej jedno z tych uprawnień, system prosi użytkownika o zezwolenie na dostęp do Urządzeń w pobliżu, jak widać na ilustracji 1.

Ten fragment kodu pokazuje, jak deklarować uprawnienia związane z Bluetoothem w aplikacji, która jest 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 twierdzić, że aplikacja nie określa lokalizacji fizycznej;

Jeśli aplikacja nie ustala lokalizacji fizycznej na podstawie wyników skanowania Bluetooth, możesz potwierdzić, że nigdy nie korzysta z 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.

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

2. Jeśli lokalizacja nie jest potrzebna Twojej aplikacji, usuń z jej pliku manifestu uprawnienie ACCESS_FINE_LOCATION.

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>

Kierowanie na Androida 11 lub starszego

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

• Usługa BLUETOOTH jest niezbędna do realizowania dowolnej komunikacji klasycznej lub BLE, na przykład żądania połączenia, akceptowania połączenia i przesłania danych.
• ACCESS_FINE_LOCATION jest konieczne, ponieważ w Androidzie 11 i starszych może być możliwe użycie skanowania Bluetooth do zebrania informacji o lokalizacji użytkownika.

Uwaga: na urządzeniach z Androidem 8.0 lub nowszym możesz użyć CompanionDeviceManager, aby w imieniu aplikacji skanować pobliskie urządzenia bez dostępu do lokalizacji. Więcej informacji o tej opcji znajdziesz w sekcji Parowanie urządzenia towarzyszącego.

Uprawnienia do lokalizacji są uprawnieniami w czasie działania, więc musisz poprosić o te uprawnienia w czasie działania razem z ich zadeklarowaniem w pliku manifestu.

Wykrywanie lokalnych urządzeń Bluetooth

Jeśli chcesz, aby aplikacja inicjowała wykrywanie urządzenia lub manipulowała ustawieniami Bluetooth, musisz zadeklarować uprawnienie BLUETOOTH_ADMIN. Większość aplikacji potrzebuje tych uprawnień wyłącznie do wykrywania lokalnych urządzeń Bluetooth. Nie używaj innych umiejętności zapewnianych przez to uprawnienie, chyba że aplikacja jest „menedżerem mocy”, która zmienia ustawienia Bluetooth na żądanie użytkownika. Zadeklaruj te 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 11, to aby wykrywać urządzenia Bluetooth, musisz też zadeklarować uprawnienie ACCESS_BACKGROUND_LOCATION. Więcej informacji na ten temat znajdziesz w artykule na temat uzyskiwania dostępu 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 to kluczowy element aplikacji, możesz dodać do pliku manifestu flagi wskazujące to wymaganie. Element <uses-feature> pozwala określić typ sprzętu, z którego korzysta Twoja aplikacja, i określić, czy jest on wymagany.

Ten przykład pokazuje, jak wskazać, że aplikacja wymaga klasycznej wersji Bluetooth.

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

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

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

Jeśli uważasz, że ta funkcja jest wymagana w Twojej aplikacji, Sklep Google Play ukryje ją przed użytkownikami urządzeń, które nie mają tych funkcji. Dlatego ustaw wymagany atrybut 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ę urządzeniom, które nie obsługują Bluetootha klasycznej wersji ani BLE, musisz nadal umieszczać element <uses-feature> w pliku manifestu aplikacji, ale ustawić właściwość required="false". Następnie w czasie działania możesz określić dostępność funkcji za pomocą 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);