Bluetooth: requestDevice() method
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The Bluetooth.requestDevice()
method of the
Bluetooth
interface returns a Promise
to a
BluetoothDevice
object with the specified options. If there is no chooser
UI, this method returns the first device matching the criteria.
Syntax
js
requestDevice()
requestDevice(options)
Parameters
options
Optional-
An object that sets options for the device request. The available options are:
filters[]
-
An array of
BluetoothScanFilters
. This filter consists of an array ofBluetoothServiceUUID
s, aname
parameter, and anamePrefix
parameter. optionalServices[]
-
An array of
BluetoothServiceUUID
s. acceptAllDevices
-
A boolean value indicating that the requesting script can accept all Bluetooth devices. The default is
false
.
Return value
A Promise
to a BluetoothDevice
object.
Exceptions
TypeError
-
Thrown if the provided
options
do not make sense. For example,options.filters
is present andoptions.acceptAllDevices
istrue
, or ifoptions.filters
is not present andoptions.acceptAllDevices
isfalse
. Oroptions.filters
is[]
. NotFoundError
DOMException
-
Thrown if there is no Bluetooth device that matches the specified options.
SecurityError
DOMException
-
Thrown if this operation is not permitted in this context due to security concerns. For example, it is called from insecure origin.
Examples
js
// Discovery options match any devices advertising:
// . The standard heart rate service.
// . Both 16-bit service IDs 0x1802 and 0x1803.
// . A proprietary 128-bit UUID service c48e6067-5295-48d3-8d5c-0395f61792b1.
// . Devices with name "ExampleName".
// . Devices with name starting with "Prefix".
//
// And enables access to the battery service if devices
// include it, even if devices do not advertise that service.
let options = {
filters: [
{ services: ["heart_rate"] },
{ services: [0x1802, 0x1803] },
{ services: ["c48e6067-5295-48d3-8d5c-0395f61792b1"] },
{ name: "ExampleName" },
{ namePrefix: "Prefix" },
],
optionalServices: ["battery_service"],
};
navigator.bluetooth
.requestDevice(options)
.then((device) => {
console.log(`Name: ${device.name}`);
// Do something with the device.
})
.catch((error) => console.error(`Something went wrong. ${error}`));
Detailed examples are in the specification.
Specifications
Specification |
---|
Web Bluetooth # dom-bluetooth-requestdevice |
Browser compatibility
BCD tables only load in the browser