藍牙權限

如要使用應用程式的藍牙功能,您必須宣告多項 權限。此外,您也應指定應用程式是否需要 支援經典藍牙或藍牙低功耗 (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:maxSdkVersion30。這個應用程式相容性步驟可協助系統在裝置安裝 Android 12 以上版本時,只授予應用程式所需的藍牙權限。
  5. 如果應用程式會使用藍牙掃描結果判斷實際位置,請宣告 這個 ACCESS_FINE_LOCATION敬上 權限。否則,您可以明確聲明應用程式不會衍生出 實際位置

BLUETOOTH_ADVERTISEBLUETOOTH_CONNECTBLUETOOTH_SCAN 權限 則為執行階段權限。 因此,你必須明確請求使用者 才能修正應用程式的問題 藍牙裝置、讓其他裝置可供偵測,或是與其他裝置通訊 與已配對的藍牙裝置。應用程式要求至少一個 這些權限,系統會提示使用者允許您的應用程式存取 鄰近裝置:如圖 1 所示。

下列程式碼片段說明如何宣告藍牙相關 權限:

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

    <!-- 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敬上 。 可用於收集 內容。
,瞭解如何調查及移除這項存取權。

由於位置存取權是執行階段權限,因此您必須在執行階段要求這些權限,並在資訊清單中宣告這些權限。

尋找本機藍牙裝置

如果您希望應用程式啟動探索裝置功能或操控藍牙功能 就必須宣告 BLUETOOTH_ADMIN敬上 權限。大多數應用程式只需要這項權限,才能探索本機藍牙裝置。請勿使用 權限除非應用程式為「電源管理員」修改藍牙設定 能直接回應使用者要求在應用程式資訊清單檔案中宣告權限。例如:

<manifest>
...
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
...
</manifest>

如果您的應用程式支援某項服務,且可在 Android 10 (API 級別 29) 或 Android 裝置中執行 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);