藍牙權限

如要在應用程式中使用藍牙功能，您必須宣告多個權限。您也應指定應用程式是否需要支援藍牙經典或藍牙低功耗 (BLE)。如果您的應用程式不需要傳統藍牙或 BLE，但仍可從這些技術中受益，您可以在執行階段檢查是否可用。

宣告權限

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

指定 Android 12 以上版本

注意： 在 Android 8.0 (API 級別 26) 以上版本中，Companion Device Manager (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) 以下版本為目標，請在應用程式的資訊清單檔案中宣告下列權限：

  • 如要執行任何藍牙經典或 BLE 通訊作業，例如要求連線、接受連線和傳輸資料，就必須使用 BLUETOOTH。
  • 您必須使用 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);