藍牙權限

如要在應用程式中使用藍牙功能,您必須宣告多項權限。您也應指定應用程式需要支援藍牙經典或藍牙低功耗 (BLE)。如果應用程式不需要藍牙傳統版或 BLE,但仍能享有這些技術帶來的優勢,您可以在執行階段檢查可用性

宣告權限

要在應用程式中宣告的權限組合取決於應用程式的目標 SDK 版本。

指定 Android 12 以上版本

注意: 在 Android 8.0 (API 級別 26) 以上版本中,隨附裝置管理工具 (CDM) 可讓您以更簡單的方式連線至隨附裝置,而這比本節所述的權限更加簡單。CDM 系統會代表應用程式提供配對 UI,不需要位置存取權。

如要進一步控管配對和連線體驗,請使用本節說明的權限。

藍牙權限對話方塊
系統權限對話方塊,要求使用者授予應用程式權限,以便探索、宣傳及連線至鄰近裝置。

如果應用程式指定 Android 12 (API 級別 31) 以上版本,請在應用程式的資訊清單檔案中宣告下列權限:

  1. 如果您的應用程式會尋找藍牙裝置 (例如 BLE 週邊裝置),請宣告 BLUETOOTH_SCAN 權限。
  2. 如果您的應用程式可讓其他藍牙裝置偵測到目前裝置,請宣告 BLUETOOTH_ADVERTISE 權限。
  3. 如果您的應用程式會與已經配對的藍牙裝置通訊,請宣告 BLUETOOTH_CONNECT 權限。
  4. 如果是舊版藍牙相關權限宣告,請將 android:maxSdkVersion 設為 30。這項應用程式相容性步驟可協助系統在搭載 Android 12 以上版本的裝置上,只授予應用程式所需的藍牙權限。
  5. 如果應用程式使用藍牙掃描結果導出實際位置,請宣告 ACCESS_FINE_LOCATION 權限。否則,您可以嚴格斷言應用程式不會取得實際位置

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

明確聲明應用程式不會取得實際位置

如果應用程式不使用藍牙掃描結果導出實際位置,您可以加強斷言,應用程式絕對不會使用藍牙權限取得實際位置。若要這樣做,請完成下列步驟:

  1. android:usesPermissionFlags 屬性加入 BLUETOOTH_SCAN 權限宣告,然後將這個屬性的值設為 neverForLocation

  2. 如果應用程式不需要位置資訊,請從應用程式的資訊清單中移除 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);