藍牙權限

如要在應用程式中使用藍牙功能，您必須宣告多項權限。您也應指定應用程式是否需要支援藍牙傳統或藍牙低功耗 (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 權限。否則，您可以強烈聲明應用程式不會衍生實體位置資訊，並將 ACCESS_FINE_LOCATION 權限的 android:maxSdkVersion 設為 30。

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>

強烈聲明應用程式不會推導實際位置

如果應用程式不會使用藍牙掃描結果推導出實際位置，您可以強烈聲明應用程式絕不會使用藍牙權限推導出實際位置。若要這樣做，請完成下列步驟：

  1. 在 BLUETOOTH_SCAN 權限宣告中加入 android:usesPermissionFlags 屬性，並將這個屬性的值設為 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" />

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

指定 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 商店就會對不具備這項功能的裝置隱藏您的應用程式。因此，只有在應用程式沒有該功能就無法運作時，才應將 required 屬性設為 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);