Skip to main content

Web Bluetooth API

Web Bluetooth API 允許網頁應用程式與藍牙低功耗（BLE）裝置進行通訊。這個 API 提供了一個標準化的方式來連接和與藍牙裝置互動，無需安裝額外的應用程式或插件。

基本實作​

const connectBluetoothDevice = async () => {
  try {
    // 檢查 Web Bluetooth API 是否可用
    if (!navigator.bluetooth) {
      throw new Error("Web Bluetooth API is not available in this browser/environment");
    }

    console.log("Requesting device", navigator.bluetooth);

    // 請求連接藍牙裝置
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ namePrefix: "Prefix-" }],
    });

    console.log("Device", device);

    // 連接到 GATT 伺服器
    const server = await device.gatt.connect();

    // 取得服務
    const service = await server.getPrimaryService("service-uuid");

    // 取得特徵值
    const characteristic = await service.getCharacteristic("characteristic-uuid");

    // 讀取特徵值
    const value = await characteristic.readValue();

    console.log("Value:", value);
  } catch (error) {
    console.error("Error:", error.message);
    document.getElementById("status").textContent = `Error: ${error.message}`;
  }
};

常用方法與參數​

當你呼叫 navigator.bluetooth.requestDevice() 時，會進行一個用戶介面流程，讓使用者選擇他們要連接的藍牙裝置。這個方法接收一個配置物件，讓你指定一些過濾條件，以便更精確地篩選出符合需求的裝置。

navigator.bluetooth.requestDevice(options); // 方法參數結構

這個方法接受一個選項物件，裡面有幾個常用的屬性：

filters​

一個物件陣列，指定了裝置的篩選條件，幫助選擇匹配的藍牙裝置。常見的過濾條件有：

  • services：指定裝置所支持的服務（服務是藍牙裝置提供的功能，比如 "heart_rate"、"battery_service"）
  • name：裝置的名稱過濾
  • namePrefix：裝置名稱的前綴過濾

範例：

// 根據服務篩選
filters: [{ services: ["heart_rate"] }];

// 根據名稱篩選
filters: [{ name: "MyDevice" }];

// 根據名稱前綴篩選
filters: [{ namePrefix: "BLE-" }];

這會篩選出支持指定服務或符合名稱條件的裝置。

optionalServices​

這是一個選項，允許指定在選擇裝置後還要啟用的附加服務。例如，你可能想在選擇藍牙裝置後，除了主要服務，還希望能與其它服務進行交互。

範例：

optionalServices: ["heart_rate", "device_information", "battery_service"];

acceptAllDevices​

一個布林值（true 或 false），如果設定為 true，它會允許列出所有藍牙裝置，而不需要依賴任何過濾條件。這通常是當你不確定要連接的裝置是哪一個時使用。

範例：

acceptAllDevices: true;

若設定為 true，則不會使用 filters 或 optionalServices，而是顯示所有可用裝置。

瀏覽器支援度​

目前除了 Google Chrome、Microsoft Edge 和 Opera 外，Web Bluetooth API 的支援還是比較有限的。以下是目前支援 Web Bluetooth 的瀏覽器及其版本：

支援 Web Bluetooth 的瀏覽器​

1. Google Chrome​

  • 版本：支持 Chrome 56 及以上版本（桌面和 Android 版本都支援）
  • 平台：Windows、macOS、Linux、Android

2. Microsoft Edge​

  • 版本：支持 Edge 79 及以上版本（基於 Chromium 的版本）
  • 平台：Windows、macOS

3. Opera​

  • 版本：支持 Opera 42 及以上版本（基於 Chromium 的版本）
  • 平台：Windows、macOS、Linux

4. Brave​

  • 版本：Brave 也基於 Chromium，因此它也支援 Web Bluetooth API
  • 平台：Windows、macOS、Linux

5. Samsung Internet​

  • 版本：支持 Web Bluetooth API，並且主要用於 Android 設備
  • 平台：Android

不支援 Web Bluetooth 的瀏覽器​

1. Safari（桌面和 iOS）​

  • 目前 Safari 不支援 Web Bluetooth API，Apple 沒有實現這項功能，並且可能會在未來的版本中加入或選擇不支持

2. Firefox​

  • 目前 Firefox 並不支援 Web Bluetooth API，Mozilla 也沒有在短期內添加這項功能的計劃

結論​

目前 Web Bluetooth 支援的瀏覽器基本都是基於 Chromium 引擎的瀏覽器，這些瀏覽器支援範圍比較廣，但 Safari 和 Firefox 仍然不支援。因此，如果你打算開發依賴 Web Bluetooth 的應用，最好推薦用戶使用 Chrome、Edge、Opera 或 Brave 等瀏覽器。

Web 平台限制​

在 Web 平台上，藍牙功能有限：

  • 無法自動發現服務和特徵值：需要預先知道要連接的服務和特徵值的 UUID
  • 需要手動指定服務 UUID 和特徵值 UUID：開發者必須事先了解目標裝置的服務結構
  • 建議在移動設備上使用完整功能：移動設備上的 Web Bluetooth 支援通常更完整

注意事項​

  • Web Bluetooth API 只能在 HTTPS 環境下使用（localhost 除外）
  • 需要用戶明確授權才能連接藍牙裝置
  • 某些藍牙功能可能受到瀏覽器安全策略限制