如要在應用程式中使用藍牙功能,您必須宣告多項權限。您也應指定應用程式需要支援藍牙經典或藍牙低功耗 (BLE)。如果應用程式不需要藍牙傳統版或 BLE,但仍能享有這些技術帶來的優勢,您可以在執行階段檢查可用性。
宣告權限
要在應用程式中宣告的權限組合取決於應用程式的目標 SDK 版本。
指定 Android 12 以上版本
注意: 在 Android 8.0 (API 級別 26) 以上版本中,隨附裝置管理工具 (CDM) 可讓您以更簡單的方式連線至隨附裝置,而這比本節所述的權限更加簡單。CDM 系統會代表應用程式提供配對 UI,不需要位置存取權。
如要進一步控管配對和連線體驗,請使用本節說明的權限。
如果應用程式指定 Android 12 (API 級別 31) 以上版本,請在應用程式的資訊清單檔案中宣告下列權限:
- 如果您的應用程式會尋找藍牙裝置 (例如 BLE 週邊裝置),請宣告
BLUETOOTH_SCAN
權限。 - 如果您的應用程式可讓其他藍牙裝置偵測到目前裝置,請宣告
BLUETOOTH_ADVERTISE
權限。 - 如果您的應用程式會與已經配對的藍牙裝置通訊,請宣告
BLUETOOTH_CONNECT
權限。 - 如果是舊版藍牙相關權限宣告,請將
android:maxSdkVersion
設為30
。這項應用程式相容性步驟可協助系統在搭載 Android 12 以上版本的裝置上,只授予應用程式所需的藍牙權限。 - 如果應用程式使用藍牙掃描結果導出實際位置,請宣告
ACCESS_FINE_LOCATION
權限。否則,您可以嚴格斷言應用程式不會取得實際位置。
BLUETOOTH_ADVERTISE
、BLUETOOTH_CONNECT
和 BLUETOOTH_SCAN
權限為執行階段權限。因此,您必須在應用程式中明確要求使用者核准,才能尋找藍牙裝置、讓其他裝置偵測到裝置,或是與已經配對的藍牙裝置進行通訊。當應用程式要求至少一項權限時,系統會提示使用者允許應用程式存取「鄰近裝置」,如圖 1 所示。
下列程式碼片段示範如何在指定 Android 12 以上版本時,在應用程式中宣告藍牙相關權限:
<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>
明確聲明應用程式不會取得實際位置
如果應用程式不使用藍牙掃描結果導出實際位置,您可以加強斷言,應用程式絕對不會使用藍牙權限取得實際位置。若要這樣做,請完成下列步驟:
將
android:usesPermissionFlags
屬性加入BLUETOOTH_SCAN
權限宣告,然後將這個屬性的值設為neverForLocation
。如果應用程式不需要位置資訊,請從應用程式的資訊清單中移除
ACCESS_FINE_LOCATION
權限。
以下程式碼片段說明如何更新應用程式的資訊清單檔案:
<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>
指定 Android 11 以下版本為目標
如果應用程式指定 Android 11 (API 級別 30) 以下版本為目標,請在應用程式的資訊清單檔案中宣告下列權限:
- 必須使用
BLUETOOTH
才能執行任何藍牙傳統或 BLE 通訊,例如要求連線、接受連線及傳輸資料。 ACCESS_FINE_LOCATION
為必要項目,因為在 Android 11 以下版本中,藍牙掃描可能可用來收集使用者位置資訊的相關資訊。
由於位置存取權是執行階段權限,因此您必須在執行階段要求這些權限,並在資訊清單中宣告這些權限。
尋找附近的藍牙裝置
如果您希望應用程式啟動裝置探索或控管藍牙設定,您必須宣告 BLUETOOTH_ADMIN
權限。大多數應用程式僅需要這項權限才能搜尋本機藍牙裝置。請勿使用此權限授予的其他功能,除非應用程式是讓應用程式在使用者要求時修改藍牙設定的「電源管理員」。在應用程式資訊清單檔案中宣告權限。例如:
<manifest>
...
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
...
</manifest>
如果您的應用程式支援服務,且可在 Android 10 (API 級別 29) 或 Android 11 上執行,則您也必須宣告 ACCESS_BACKGROUND_LOCATION
權限,以便探索藍牙裝置。如要進一步瞭解這項規定,請參閱「在背景存取位置資訊」。
下列程式碼片段說明如何宣告 ACCESS_BACKGROUND_LOCATION
權限:
<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
...
</manifest>
如要進一步瞭解如何宣告應用程式權限,請參閱 <uses-permission>
參考資料。
指定藍牙功能用途
如果藍牙是應用程式的重要部分,您可以在資訊清單檔案中新增標記,藉此表明這項需求。<uses-feature>
元素可讓您指定應用程式使用的硬體類型,以及是否必要。
本例說明如何指出應用程式需要使用傳統版藍牙。
<uses-feature android:name="android.hardware.bluetooth" android:required="true"/>
如果應用程式需要使用藍牙低功耗技術,您可以使用下列功能:
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
如果您表示應用程式需要該功能,Google Play 商店就會針對沒有這些功能的裝置隱藏該應用程式。因此,建議您只有在應用程式需要該功能才能運作時,才將必要的屬性設為 true
。
在執行階段檢查功能可用性
如果想讓應用程式適用於不支援藍牙傳統版或 BLE 的裝置,您仍應在應用程式的資訊清單中加入 <uses-feature>
元素,但要設定 required="false"
。然後在執行階段使用 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);