Để sử dụng tính năng Bluetooth trong ứng dụng của mình, bạn phải khai báo một số quyền truy cập. Bạn cũng nên chỉ định xem ứng dụng của bạn có yêu cầu hỗ trợ cho Bluetooth cổ điển hoặc Bluetooth năng lượng thấp (BLE). Nếu ứng dụng không yêu cầu Bluetooth cổ điển hoặc BLE nhưng vẫn có thể hưởng lợi từ mà bạn có thể kiểm tra tính sẵn có trong thời gian chạy.
Khai báo quyền
Tập hợp quyền mà bạn khai báo trong ứng dụng phụ thuộc vào mục tiêu của ứng dụng Phiên bản SDK.
Nhắm mục tiêu đến Android 12 trở lên
Lưu ý: Trên Android 8.0 (API cấp 26) trở lên, Quảng cáo đồng hành Trình quản lý thiết bị (CDM) cung cấp phương thức đơn giản hơn để kết nối với thiết bị đồng hành so với các quyền được mô tả trong phần này. Chiến lược phát hành đĩa đơn Hệ thống CDM cung cấp một giao diện người dùng ghép nối thay mặt cho ứng dụng của bạn và không yêu cầu quyền truy cập thông tin vị trí.
Nếu bạn muốn có nhiều quyền kiểm soát hơn đối với trải nghiệm ghép nối và kết nối, hãy sử dụng các quyền được mô tả trong phần này.
Nếu ứng dụng của bạn nhắm đến Android 12 (API cấp 31) trở lên, hãy khai báo những nội dung sau các quyền trong tệp kê khai của ứng dụng:
- Nếu ứng dụng của bạn tìm kiếm Bluetooth
trên thiết bị, chẳng hạn như
thiết bị ngoại vi BLE, khai báo
BLUETOOTH_SCAN
quyền. - Nếu ứng dụng của bạn đặt thiết bị hiện tại ở chế độ có thể phát hiện qua Bluetooth khác
thiết bị,
khai báo
BLUETOOTH_ADVERTISE
quyền. - Nếu ứng dụng của bạn giao tiếp với Bluetooth đã được ghép nối
thiết bị nào thì hãy khai báo
BLUETOOTH_CONNECT
quyền. - Đối với các nội dung khai báo quyền cũ liên quan đến Bluetooth, hãy đặt
android:maxSdkVersion
thành30
. Bước này về khả năng tương thích của ứng dụng giúp hệ thống chỉ cấp cho ứng dụng của bạn những quyền Bluetooth mà ứng dụng cần khi được cài đặt thiết bị chạy Android 12 trở lên. - Nếu ứng dụng của bạn dùng kết quả quét Bluetooth để tìm vị trí thực tế, hãy khai báo
thời gian
ACCESS_FINE_LOCATION
quyền. Nếu không, bạn có thể khẳng định chắc chắn rằng ứng dụng của mình không dẫn đến vị trí thực tế.
Các quyền BLUETOOTH_ADVERTISE
, BLUETOOTH_CONNECT
và BLUETOOTH_SCAN
là quyền khi bắt đầu chạy.
Do đó, bạn phải yêu cầu người dùng một cách rõ ràng
lượt phê duyệt trong ứng dụng của mình trước khi bạn có thể tìm kiếm
Thiết bị Bluetooth, đặt thiết bị ở chế độ có thể phát hiện được với các thiết bị khác hoặc giao tiếp
với thiết bị Bluetooth đã được ghép nối. Khi ứng dụng của bạn yêu cầu ít nhất một trong
những quyền này, hệ thống sẽ nhắc người dùng cho phép ứng dụng của bạn truy cập
Thiết bị ở gần, như minh hoạ trong hình 1.
Đoạn mã sau đây minh hoạ cách khai báo vấn đề liên quan đến Bluetooth các quyền trong ứng dụng của bạn nếu ứng dụng đó nhắm đến Android 12 trở lên:
<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>
Xác nhận chắc chắn rằng ứng dụng của bạn không lấy dữ liệu vị trí thực tế
Nếu ứng dụng của bạn không sử dụng kết quả quét Bluetooth để xác định vị trí thực tế, bạn có thể đưa ra khẳng định rõ ràng rằng ứng dụng của bạn không bao giờ sử dụng quyền truy cập Bluetooth để xác định vị trí thực tế. Để thực hiện điều này, vui lòng hoàn thành các bước sau:
Thêm thuộc tính
android:usesPermissionFlags
vàoBLUETOOTH_SCAN
khai báo quyền rồi đặt giá trị của thuộc tính này thànhneverForLocation
.Nếu ứng dụng của bạn không cần thông tin vị trí, hãy xoá
ACCESS_FINE_LOCATION
trong tệp kê khai của ứng dụng.
Đoạn mã sau đây cho biết cách cập nhật tệp kê khai của ứng dụng:
<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>
Nhắm mục tiêu đến Android 11 trở xuống
Nếu ứng dụng của bạn nhắm đến Android 11 (API cấp 30) trở xuống, hãy khai báo những nội dung sau các quyền trong tệp kê khai của ứng dụng:
- Cần có
BLUETOOTH
để thực hiện bất kỳ giao tiếp Bluetooth cổ điển hoặc BLE nào, chẳng hạn như yêu cầu kết nối, chấp nhận kết nối và chuyển dữ liệu. ACCESS_FINE_LOCATION
là cần thiết vì trên Android 11 trở xuống, tính năng quét tìm Bluetooth có thể được dùng để thu thập thông tin về vị trí của người dùng.
Vì quyền truy cập thông tin vị trí là quyền khi bắt đầu chạy, bạn phải yêu cầu các quyền này trong thời gian chạy cùng với việc khai báo các trường đó trong tệp kê khai.
Khám phá các thiết bị Bluetooth trong mạng
Nếu bạn muốn ứng dụng của mình bắt đầu khám phá thiết bị hoặc thao tác với Bluetooth
, bạn phải khai báo các
BLUETOOTH_ADMIN
quyền. Hầu hết ứng dụng chỉ cần quyền này để có thể khám phá
thiết bị Bluetooth cục bộ. Không sử dụng các tính năng khác được cấp bằng cách này
trừ khi ứng dụng là "trình quản lý nguồn" sửa đổi chế độ cài đặt Bluetooth
theo yêu cầu của người dùng. Khai báo quyền trong tệp kê khai ứng dụng. Ví dụ:
<manifest>
...
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
...
</manifest>
Nếu ứng dụng của bạn hỗ trợ một dịch vụ và có thể chạy trên Android 10 (API cấp 29) hoặc
Trên Android 11, bạn cũng phải khai báo
ACCESS_BACKGROUND_LOCATION
quyền khám phá thiết bị Bluetooth. Để biết thêm thông tin về vấn đề này
hãy xem phần Quyền truy cập thông tin vị trí trong
màu nền.
Đoạn mã sau đây cho biết cách khai báo ACCESS_BACKGROUND_LOCATION
quyền:
<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
...
</manifest>
Xem <uses-permission>
để biết thêm thông tin về việc khai báo quyền cho ứng dụng.
Chỉ định mức sử dụng tính năng Bluetooth
Nếu Bluetooth là một phần quan trọng của ứng dụng, bạn có thể thêm cờ vào tệp kê khai
tệp cho biết yêu cầu này. Chiến lược phát hành đĩa đơn
Phần tử <uses-feature>
cho phép
bạn chỉ định loại phần cứng mà ứng dụng của bạn sử dụng và liệu ứng dụng đó có
là bắt buộc.
Ví dụ này minh hoạ cách cho biết rằng cần có Bluetooth cổ điển để .
<uses-feature android:name="android.hardware.bluetooth" android:required="true"/>
Nếu ứng dụng của bạn dùng Bluetooth năng lượng thấp, thì bạn có thể dùng những cách sau:
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
Nếu bạn nói rằng tính năng này là bắt buộc đối với ứng dụng của bạn thì Cửa hàng Google Play sẽ
ẩn ứng dụng khỏi người dùng trên thiết bị thiếu các tính năng đó. Vì lý do này, bạn
chỉ nên đặt thuộc tính bắt buộc thành true
nếu ứng dụng của bạn không thể hoạt động nếu không có
tính năng này.
Kiểm tra khả năng hoạt động của tính năng trong thời gian chạy
Để cung cấp ứng dụng của bạn cho các thiết bị không hỗ trợ Bluetooth phiên bản cũ hoặc
BLE, bạn vẫn nên đưa phần tử <uses-feature>
vào
tệp kê khai nhưng đặt required="false"
. Sau đó, trong thời gian chạy, bạn có thể xác định
phạm vi cung cấp tính năng dựa trên
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);