Bluetooth.requestDevice()
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
Bluetooth.requestDevice([options])
.then(function(bluetoothDevice) { /* ... */ })
Return value
A Promise
to a BluetoothDevice
object.
Parameters
- options Optional
-
An object that sets options for the device request. The available options are:
-
filters[]
: An array ofBluetoothScanFilters
. This filter consists of an array ofBluetoothServiceUUID
s, aname
parameter, and anamePrefix
parameter. optionalServices[]
: An array ofBluetoothServiceUUID
s.-
acceptAllDevices
: A boolean value indicating that the requesting script can accept all Bluetooth devices. The default isfalse
.
-
Exceptions
TypeError
DOMException
-
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.
Example
// 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(function(device) {
console.log('Name: ' + device.name);
// Do something with the device.
})
.catch(function(error) {
console.log("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