Quyền truy cập Bluetooth

Để sử dụng các tính năng Bluetooth trong ứng dụng, bạn phải khai báo một số quyền. Bạn cũng nên chỉ định xem ứng dụng của bạn có yêu cầu hỗ trợ Bluetooth Classic hay Bluetooth năng lượng thấp (BLE) hay không. Nếu ứng dụng của bạn không yêu cầu Bluetooth Classic hoặc BLE nhưng vẫn có thể hưởng lợi từ các công nghệ này, thì bạn có thể kiểm tra xem có sẵn trong thời gian chạy hay không.

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 phiên bản SDK mục tiêu của ứng dụng.

Nhắm đến Android 12 trở lên

Lưu ý: Trên Android 8.0 (cấp độ API 26) trở lên, Trình quản lý thiết bị đồng hành (CDM) cung cấp một phương thức kết nối với thiết bị đồng hành hợp lý hơn so với các quyền được mô tả trong phần này. Hệ thống CDM cung cấp 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 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.

Hộp thoại quyền hệ thống, yêu cầu người dùng cấp quyền cho ứng dụng để khám phá, quảng cáo và kết nối với các thiết bị ở gần.

Nếu ứng dụng của bạn nhắm đến Android 12 (cấp độ API 31) trở lên, hãy khai báo các quyền sau trong tệp kê khai của ứng dụng:

1. Nếu ứng dụng của bạn tìm thiết bị Bluetooth, chẳng hạn như thiết bị ngoại vi BLE, hãy khai báo quyền BLUETOOTH_SCAN.
2. Nếu ứng dụng của bạn cho phép các thiết bị Bluetooth khác phát hiện thiết bị hiện tại, hãy khai báo quyền BLUETOOTH_ADVERTISE.
3. Nếu ứng dụng của bạn giao tiếp với các thiết bị Bluetooth đã ghép nối, hãy khai báo quyền BLUETOOTH_CONNECT.
4. Đối với các nội dung khai báo quyền liên quan đến Bluetooth cũ, hãy đặt android:maxSdkVersion thành 30. Bước tương thích ứng dụng này giúp hệ thống chỉ cấp cho ứng dụng của bạn các quyền Bluetooth cần thiết khi cài đặt trên các thiết bị chạy Android 12 trở lên.
5. Nếu ứng dụng của bạn sử dụng kết quả quét Bluetooth để lấy thông tin vị trí thực tế, hãy khai báo quyền ACCESS_FINE_LOCATION. Nếu không, bạn có thể khẳng định chắc chắn rằng ứng dụng của bạn không lấy thông tin vị trí thực tế và đặt android:maxSdkVersion thành 30 cho quyền ACCESS_FINE_LOCATION.

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 phê duyệt một cách rõ ràng trong ứng dụng trước khi có thể tìm thiết bị Bluetooth, đặt thiết bị ở chế độ có thể phát hiện đối với các thiết bị khác hoặc giao tiếp với các thiết bị Bluetooth đã ghép nối. Khi ứng dụng của bạn yêu cầu ít nhất một trong các quyền này, hệ thống sẽ nhắc người dùng cho phép ứng dụng truy cập vào Thiết bị ở gần, như minh hoạ trong hình 1.

Đoạn mã sau đây minh hoạ cách khai báo các quyền liên quan đến Bluetooth trong ứng dụng 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>

Khẳng định chắc chắn rằng ứng dụng của bạn không lấy thông tin vị trí thực tế

Nếu ứng dụng của bạn không sử dụng kết quả quét tìm thiết bị Bluetooth để lấy thông tin vị trí thực tế, thì bạn có thể khẳng định chắc chắn rằng ứng dụng của bạn không bao giờ sử dụng quyền Bluetooth để lấy thông tin 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:

1. Thêm thuộc tính android:usesPermissionFlags vào phần khai báo quyền BLUETOOTH_SCAN, sau đó đặt giá trị của thuộc tính này thành neverForLocation.

   Lưu ý: Nếu bạn đưa neverForLocation vào android:usesPermissionFlags, thì một số đèn hiệu BLE sẽ bị lọc khỏi kết quả quét.

2. Nếu ứng dụng của bạn không cần thông tin vị trí, hãy xoá quyền ACCESS_FINE_LOCATION khỏi 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" />

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

Nhắm đến Android 11 trở xuống

Nếu ứng dụng của bạn nhắm đến Android 11 (cấp độ API 30) trở xuống, hãy khai báo các quyền sau trong tệp kê khai của ứng dụng:

• Bạn cần có quyền BLUETOOTH để thực hiện mọi hoạt động giao tiếp Bluetooth Classic hoặc BLE, 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, quá trình quét Bluetooth có thể được dùng để thu thập thông tin về vị trí của người dùng.

Lưu ý: Trên các thiết bị chạy Android 8.0 trở lên, bạn có thể sử dụng CompanionDeviceManager để thay mặt ứng dụng quét tìm các thiết bị đồng hành ở gần mà không cần quyền truy cập vị trí. Để biết thêm thông tin về lựa chọn này, hãy xem phần Ghép nối thiết bị đồng hành.

Vì quyền truy cập vị trí là quyền khi bắt đầu chạy, nên bạn phải yêu cầu các quyền này khi bắt đầu chạy cùng với việc khai báo các quyền đó trong tệp kê khai.

Khám phá các thiết bị Bluetooth cục bộ

Nếu muốn ứng dụng của mình bắt đầu quá trình khám phá thiết bị hoặc thao tác với chế độ cài đặt Bluetooth, bạn phải khai báo quyền BLUETOOTH_ADMIN. Hầu hết các ứng dụng chỉ cần quyền này để có thể khám phá các thiết bị Bluetooth cục bộ. Đừng sử dụng các khả năng khác mà quyền này cấp, trừ phi ứng dụng là một "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 (cấp độ API 29) hoặc Android 11, thì bạn cũng phải khai báo quyền ACCESS_BACKGROUND_LOCATION để khám phá các thiết bị Bluetooth. Để biết thêm thông tin về yêu cầu này, hãy xem phần Truy cập thông tin vị trí ở chế độ nền.

Đoạn mã sau đây cho biết cách khai báo quyền ACCESS_BACKGROUND_LOCATION:

<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
...
</manifest>

Hãy xem tài liệu tham khảo <uses-permission> để biết thêm thông tin về cách khai báo quyền cho ứng dụng.

Chỉ định cách sử dụng tính năng Bluetooth

Nếu Bluetooth là một phần quan trọng trong ứng dụng, bạn có thể thêm cờ vào tệp kê khai để cho biết yêu cầu này. Phần tử <uses-feature> cho phép bạn chỉ định loại phần cứng mà ứng dụng sử dụng và liệu phần cứng đó có bắt buộc hay không.

Ví dụ này cho biết cách chỉ định rằng ứng dụng của bạn cần có Bluetooth Classic.

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

Nếu ứng dụng của bạn dựa vào Bluetooth năng lượng thấp, bạn có thể sử dụng các tính năng sau:

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

Nếu bạn cho biết tính năng này là bắt buộc đối với ứng dụng, thì Cửa hàng Google Play sẽ ẩn ứng dụng của bạn khỏi người dùng trên các thiết bị không 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 không thể hoạt động khi không có tính năng này.

Kiểm tra phạm vi cung cấp của tính năng trong thời gian chạy

Để cung cấp ứng dụng cho các thiết bị không hỗ trợ Bluetooth Classic hoặc BLE, bạn vẫn nên đưa phần tử <uses-feature> vào tệp kê khai của ứng dụng, nhưng hãy đặt required="false". Sau đó, trong thời gian chạy, bạn có thể xác định tính năng có sẵn bằng cách sử dụng 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);