Bluetooth.getDevices() — Methode · JavaScript-Referenz

Signatur

Bluetooth.prototype.getDevices()

Beschreibung

navigator.bluetooth.getDevices() gibt ein Promise zurück, das mit einem Array von BluetoothDevice-Objekten erfüllt wird. Enthalten sind alle Geräte, für die der Nutzer diesem Ursprung zuvor über requestDevice() den Zugriff erlaubt hat. Anders als requestDevice() zeigt die Methode keinen Auswahldialog und benötigt keine Nutzeraktivierung.

Typischer Einsatzzweck ist das Wiederverbinden nach einem Neuladen der Seite: Statt den Nutzer bei jedem Besuch erneut ein Gerät auswählen zu lassen, fragt die Anwendung die bereits genehmigten Geräte ab und stellt über device.gatt.connect() die Verbindung wieder her. Da auch Geräte außerhalb der Funkreichweite zurückgegeben werden, empfiehlt sich vorher device.watchAdvertisements(), um festzustellen, ob das Gerät tatsächlich erreichbar ist.

Die Methode ist nur in einem sicheren Kontext (HTTPS) verfügbar und kann durch die Permissions-Policy bluetooth blockiert werden. Ein leeres Array bedeutet, dass noch keine Berechtigungen erteilt wurden – oder dass der Browser persistente Berechtigungen nicht unterstützt.

Rückgabewert

Typ

Promise<BluetoothDevice[]>

Beschreibung

Promise, das mit einem (ggf. leeren) Array von BluetoothDevice-Objekten erfüllt wird. Wird mit SecurityError abgelehnt, wenn der Zugriff durch Permissions-Policy oder unsicheren Kontext verweigert ist.

Beispiele

Bereits genehmigte Geräte auflisten

const listDevices = async () => {
  if (!navigator.bluetooth?.getDevices) {
    console.warn('getDevices() wird nicht unterstützt');
    return;
  }
  const devices = await navigator.bluetooth.getDevices();
  console.log(`${devices.length} genehmigte(s) Gerät(e):`);
  for (const device of devices) {
    console.log(`- ${device.name ?? 'Unbekannt'} (${device.id})`);
  }
};

listDevices();

1 genehmigte(s) Gerät(e): - Herzfrequenzgurt (x3kZ8p...==)

Automatisch wiederverbinden nach Seiten-Reload

const reconnect = async () => {
  const devices = await navigator.bluetooth.getDevices();
  const device = devices.find((d) => d.name === 'Herzfrequenzgurt');
  if (!device) return null;

  // Erst prüfen, ob das Gerät in Reichweite ist
  const ac = new AbortController();
  const inRange = new Promise((resolve) => {
    device.addEventListener('advertisementreceived', () => {
      ac.abort(); // Scannen beenden
      resolve(true);
    }, { once: true });
  });
  await device.watchAdvertisements({ signal: ac.signal });

  await inRange;
  const server = await device.gatt.connect();
  console.log('Verbunden:', server.connected);
  return server;
};

reconnect().catch(console.error);

Verbunden: true

Fallback auf requestDevice()

const getHeartRateDevice = async () => {
  const known = await navigator.bluetooth.getDevices();
  if (known.length > 0) return known[0];

  // Benötigt Nutzeraktivierung, z. B. im Klick-Handler aufrufen
  return navigator.bluetooth.requestDevice({
    filters: [{ services: ['heart_rate'] }]
  });
};

document.querySelector('#connect').addEventListener('click', async () => {
  const device = await getHeartRateDevice();
  console.log('Gerät:', device.name);
});

Gerät: Herzfrequenzgurt

// Wichtig · Fallstricke

Experimentell: Nur in Chromium-Browsern verfügbar und dort je nach Version hinter dem Flag chrome://flags/#enable-web-bluetooth-new-permissions-backend. Firefox und Safari unterstützen Web Bluetooth überhaupt nicht – immer per Feature-Erkennung ('getDevices' in navigator.bluetooth) prüfen.
Zurückgegebene Geräte sind nicht automatisch verbunden und evtl. außer Reichweite; ein direkter gatt.connect() kann daher fehlschlagen oder lange hängen.
Die device.id ist pro Ursprung zufällig und stabil, aber nicht die MAC-Adresse – nicht über Ursprünge hinweg vergleichbar.
Nutzer können Berechtigungen in den Website-Einstellungen widerrufen; mit device.forget() kann die Anwendung selbst eine Berechtigung aufgeben.
Nur in sicheren Kontexten (HTTPS) und nicht in Cross-Origin-iframes ohne allow="bluetooth".

Siehe auch

Bluetooth Selection.setPosition() Bluetooth.requestDevice() Bluetooth.getAvailability() BluetoothUUID.getService()