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
Uwaga: w Androidzie 8.0 (poziom interfejsu API 26) i nowszych Menedżer urządzeń towarzyszących (CDM) zapewnia łatwiejszą metodę łączenia się z urządzeniami towarzyszącymi niż w przypadku uprawnień opisanych w tej sekcji. System CDM udostępnia interfejs parowania w imieniu aplikacji i nie wymaga dostępu do lokalizacji.
Jeśli chcesz mieć większą kontrolę nad parowaniem i łączeniem, skorzystaj z uprawnień opisanych w tej sekcji.
Jeśli Twoja aplikacja jest kierowana na Androida 12 (poziom interfejsu API 31) lub nowszego, w pliku manifestu aplikacji zadeklaruj te uprawnienia:
- Jeśli Twoja aplikacja szuka urządzeń Bluetooth, takich jak urządzenia peryferyjne BLE, zadeklaruj uprawnienie
BLUETOOTH_SCAN
. - Jeśli aplikacja udostępnia bieżące urządzenie innym urządzeniom Bluetooth, zadeklaruj uprawnienie
BLUETOOTH_ADVERTISE
. - Jeśli Twoja aplikacja komunikuje się z już sparowanymi urządzeniami Bluetooth, zadeklaruj uprawnienie
BLUETOOTH_CONNECT
. - W przypadku starszych deklaracji uprawnień dotyczących Bluetootha ustaw
android:maxSdkVersion
na30
. 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. - 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ć:
Dodaj atrybut
android:usesPermissionFlags
do deklaracji uprawnieńBLUETOOTH_SCAN
i ustaw wartość tego atrybutu naneverForLocation
.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()
:
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);