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 makes 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
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
requestDevice |
56 |
79 |
No |
No |
43 |
No |
No |
56 |
No |
43 |
No |
6.0 |
© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Bluetooth/requestDevice