藍牙權限

如要使用應用程式的藍牙功能，您必須宣告多項 權限。此外，您也應指定應用程式是否需要 支援經典藍牙或藍牙低功耗 (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_ADVERTISE、BLUETOOTH_CONNECT 和 BLUETOOTH_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。

   注意： 如果您在neverForLocation android:usesPermissionFlags，部分 BLE 信標已從掃描作業中篩除 結果。

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 8.0 以上版本的裝置上，您可以使用 CompanionDeviceManager 可以代表您的應用程式掃描鄰近的隨附裝置 要求位置存取權。如要進一步瞭解這個選項，請參閱夥伴模式 裝置配對

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

尋找本機藍牙裝置

如果您希望應用程式啟動探索裝置功能或操控藍牙功能 就必須宣告 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);