Quyền truy cập Bluetooth

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

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:

1. 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.
2. 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.
3. 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.
4. Đố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ành 30. 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.
5. 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:

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

2. 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():

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

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