Intent to Ship: Web Bluetooth getDevices(), BluetoothDevice.watchAdvertisements(), and BluetoothAdvertisingEvent

[Ovidio Ruiz-Henríquez]

Contact emails

odej...@chromium.org

Explainer

https://docs.google.com/document/d/1h3uAVXJARHrNWaNACUPiQhLt7XI-fFFQoARSs1WgMDM/edit#heading=h.jdnga4sjs82y

Design docs/spec

Specification: https://webbluetoothcg.github.io/web-bluetooth/

https://docs.google.com/document/d/1h3uAVXJARHrNWaNACUPiQhLt7XI-fFFQoARSs1WgMDM/edit#heading=h.jdnga4sjs82y

TAG review

Web Bluetooth API: https://github.com/w3ctag/design-reviews/issues/139

Web Bluetooth Scanning API: https://github.com/w3ctag/design-reviews/issues/333

The Web Bluetooth API TAG review discusses how Web Bluetooth mitigates privacy risks through a user prompt. watchAdvertisements() can only be used on a BluetoothDevice object, which is only available after being granted device access through the prompt.

The Bluetooth Scanning API mentions a privacy issue around knowing the devices around the user. watchAdvertisements() only notifies the web app if an advertisement is received for the BluetoothDevice that it was called on.

Summary

Chrome's implementation of Web Bluetooth does not have a way for websites to get a list of permitted devices. This feature adds the Bluetooth.getDevices() method. getDevices() will return a list of BluetoothDevice objects that the current origin has been granted permission to use by the user.

The BluetoothDevice.watchAdvertisements() method will enable web apps to receive BluetoothAdvertisingEvents when the system receives an advertisement packet from a watched device. These two APIs will be used in conjunction to be able to reconnect to previously permitted devices.

Debuggability

No extra DevTools support is needed. Chromium has a bluetooth-internals page where developers can debug their Bluetooth devices. This page is accessed via chrome://bluetooth-internals in Chrome and edge://bluetooth-internals in Edge.

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux,

Chrome OS, Android, and Android WebView)?

No

https://github.com/WebBluetoothCG/web-bluetooth/blob/master/implementation-status.md#implementation-status

Note: watchAdvertisements() will not be supported on Linux due to limitations from BlueZ.

Is this feature fully tested by web-platform-tests?

Yes, Web platform tests were added as this feature was implemented. The tests use the Web Bluetooth testing API and were added to the wpt/bluetooth directory.

getDevices(): https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/web_tests/external/wpt/bluetooth/getDevices/

watchAdvertisements(): https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/web_tests/external/wpt/bluetooth/device/watchAdvertisements/

https://github.com/web-platform-tests/wpt/tree/master/bluetooth

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5180688812736512

https://chromestatus.com/feature/4797798639730688 

This intent message was generated by Chrome Platform Status.

[Ovidio Ruiz-Henríquez]

Just to clarify, watchAdvertisements() is part of the Web Bluetooth API, so the Web Bluetooth API TAG review applies more to it. I included the TAG review for the Web Bluetooth Scanning API because the watchAdvertisements() API does start a scan, but only for the device for which it is called on. This I2S is NOT for the Web Bluetooth Scanning API.

[Chris Harrelson]

Hi, I have a few questions about this intent.

1. In the spec, watchAdvertisements is marked as "not stable". Should that be a concern?

2. The Web Bluetooth Scanning TAG review ended on Nov 26 2019 due to "lack of progress". Were all of the substantive pieces of feedback offered there taken into consideration?

3. Could you fill out the Risks section of the template?

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/791df9df-50fc-43bb-92d5-d46a04e9ceecn%40chromium.org.

[Ovidio Ruiz-Henríquez]

Sure, I'm happy to answer them.

1. The "not stable" watermark is used to indicate that the API hasn't been implemented yet. I need to go an update it to not display the watermark anymore.

2. I included the TAG review for Web Bluetooth Scanning because the watchAdvertisements() API starts a scan. However, you can only call this method if you have a BluetoothDevice object, which you can only acquire after the user has granted the site permission to use the device through a chooser dialog. If focus is lost for the window, the watch advertisements operation stops. The operation can also be stopped using an AbortController. I don't think that the rest of the feedback in that TAG review applies, since the scan operation started with this API will not include other devices that are around the user.

3. Yes, here it is:

Risks

Interoperability and Compatibility

The Web Bluetooth API as a whole has only been implemented in Chromium, therefore there is high interoperability risk. However, there are 170+ tests in Web Platform Tests that other implementers can use.

Edge: Shipped

Firefox: No signals (based on discussion on standards-positions#95). There were concerns shared with WebUSB and WebMIDI, but ultimately the discussion ended without a distinct signal on the API.

Safari: No signals (bug)

Web / Framework developers: Mostly positive with concerns about security and privacy

• Web Bluetooth API as a whole (see Intent to Ship: Web Bluetooth)
  • Mostly positive support on the WebKit bug
  • Privacy concerns several articles (1, 2, 3)
  • Some positive support with security and privacy concerns on the Firefox bug
• getDevices() and watchAdvertisements() API
  • Multiple users have requested the functionality enabled by this feature on the Crbug as well as in StackOverflow. A list of these can be found in the Developer requests section of the Web Bluetooth Persistent Permissions design document

Ergonomics

These APIs should only need to be used within the Web Bluetooth API.

Activation

Developers would be able to use these APIs as is.

[Chris Harrelson]

On Thu, Jun 25, 2020 at 3:37 PM 'Ovidio Ruiz-Henríquez' via blink-dev <blin...@chromium.org> wrote:

Sure, I'm happy to answer them.

1. The "not stable" watermark is used to indicate that the API hasn't been implemented yet. I need to go an update it to not display the watermark anymore.

2. I included the TAG review for Web Bluetooth Scanning because the watchAdvertisements() API starts a scan. However, you can only call this method if you have a BluetoothDevice object, which you can only acquire after the user has granted the site permission to use the device through a chooser dialog. If focus is lost for the window, the watch advertisements operation stops. The operation can also be stopped using an AbortController. I don't think that the rest of the feedback in that TAG review applies, since the scan operation started with this API will not include other devices that are around the user.

3. Yes, here it is:

Risks

Interoperability and Compatibility

The Web Bluetooth API as a whole has only been implemented in Chromium, therefore there is high interoperability risk. However, there are 170+ tests in Web Platform Tests that other implementers can use.

Edge: Shipped

Are the features you are proposing to ship actually already shipped on Edge? How can that be if they use Chromium also?

 

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/764dd2d4-e1cb-4e09-a52f-9eec7f8d7040n%40chromium.org.

[Ovidio Ruiz-Henríquez]

Sorry, that's my mistake. These APIs are not shipped on Edge. Web Bluetooth is however.

I also would like to clarify that Firefox does have a clear signal on Web Bluetooth now. They have a negative signal towards it.

[Ovidio Ruiz-Henríquez]

Safari similarly most likely opposes Web Bluetooth based on their webkit-dev response for Web NFC. They state that "the primary strengths of the Web is that uses can visit any website without the fear of their computing devices being permanently compromised."

[Yoav Weiss]

How confident are we that the API shape here actually solves the use-case? Do we have feedback from developers that tried the API behind a flag? Would an Origin Trial make sense here to gain more confidence that it's the right API to ship?

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/a4d77cc6-08bf-462e-972e-dd8e7b236f13n%40chromium.org.

[Ovidio Ruiz-Henríquez]

Based on other device APIs, such as WebUSB, Web Serial, and WebHID, we know that getDevices() is a reasonable shape for solving the issue of retrieving previously permitted devices. Bluetooth adds the complication that the device may or may not be in range, so the watchAdvertisements() operation starts a scan for the specific device. This operation also serves to get additional data from the device that is only present in the advertisement packet, like the transmit power, RSSI, manufacturer data, and service data.

I updated the several posts on StackOverflow about reconnecting to Bluetooth devices on subsequent browsing sessions to give these APIs a try and to provide feedback. I also had engineers from Padoa reach out to me requesting the ability to reconnect to devices that have been permitted previously, so I let them know as well.

[Yoav Weiss]

Thanks! Thoughts about an Origin Trial? Do we have partners that may be open to that?

[Ovidio Ruiz-Henríquez]

I don't think that an Origin Trial will be necessary for this feature. There's also not any specific partners. This feature solves a huge pain point in using Web Bluetooth where users had to interact with a device chooser prompt every time that they visited a page that used Web Bluetooth, so that was the main motivation for working on this feature.

[Chris Harrelson]

On Thu, Jul 9, 2020 at 11:04 AM Ovidio Ruiz-Henríquez <odej...@chromium.org> wrote:

I don't think that an Origin Trial will be necessary for this feature. There's also not any specific partners. This feature solves a huge pain point in using Web Bluetooth where users had to interact with a device chooser prompt every time that they visited a page that used Web Bluetooth, so that was the main motivation for working on this feature.

On Wed, Jul 8, 2020 at 2:28 PM Yoav Weiss <yo...@yoav.ws> wrote:

Thanks! Thoughts about an Origin Trial? Do we have partners that may be open to that?

On Wed, Jul 8, 2020 at 1:14 AM Ovidio Ruiz-Henríquez <odej...@chromium.org> wrote:

Based on other device APIs, such as WebUSB, Web Serial, and WebHID, we know that getDevices() is a reasonable shape for solving the issue of retrieving previously permitted devices. Bluetooth adds the complication that the device may or may not be in range, so the watchAdvertisements() operation starts a scan for the specific device. This operation also serves to get additional data from the device that is only present in the advertisement packet, like the transmit power, RSSI, manufacturer data, and service data.

I updated the several posts on StackOverflow about reconnecting to Bluetooth devices on subsequent browsing sessions to give these APIs a try and to provide feedback. I also had engineers from Padoa reach out to me requesting the ability to reconnect to devices that have been permitted previously, so I let them know as well.

Thanks for asking those developers to try it out.

The API owners met today and we'd like to wait for feedback from one or more of those developers that they tried it with the feature enabled and it met their needs. When that happens, please update the thread with the results. Thanks!

 

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAOyDv-K%2Bu6Wo5pgX91JR9JWCHsT0-ckjnqvdxObax_9YKOYjZw%40mail.gmail.com.

[odej...@google.com]

I've received some feedback from a developer on the bugs for the new APIs. I'll provide a brief summary of the feedback with links to the actual feedback.

Overall, getDevices() and watchAdvertisements() integrate well into their existing use case, and saves users extra clicks in order to connect their previously used devices.

For getDevices(): https://bugs.chromium.org/p/chromium/issues/detail?id=577953#c43

The developer stated that it would be nice to have a way to filter devices returned by this API, as some use cases may have many Bluetooth devices. They also suggested that it would be nice to only return devices that are currently in range. These suggestions would require some more thought and work, since it would mean that getDevices() would need to wait a certain amount of time to allow the system to scan for nearby Bluetooth devices.

For watchAdvertisements(): https://bugs.chromium.org/p/chromium/issues/detail?id=654897#c18

The developer stated that it would be nice to have a single API that can watch for advertisements on all permitted devices, rather than having to iterate over the devices and calling watchAdvertisements() on them. Additionally, they stated that using AbortController for cancelling a watchAdvertisements() operation feels less readable than having something like an unwatchAdvertisements() API. watchAdvertisements() is the first Web Bluetooth API to use AbortController, but the idea has been discussed a bit in https://github.com/WebBluetoothCG/web-bluetooth/issues/439#issuecomment-662936648. The developer also added their feedback about using AbortController to that GitHub issue. 

To unsubscribe from this group and stop receiving emails from it, send an email to blin...@chromium.org.

[Chris Harrelson]

Thanks for those updates. I have two follow-on questions:

1. Did the developer you are linking to build an actual site with the feature, or integrate the features into an existing site? I wasn't sure about that.

2. Do you plan to incorporate the second piece of feedback into a possibly revised API shape?

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/50e5c72c-b47a-4bff-859c-6c6f8b9d0710o%40chromium.org.

[odej...@google.com]

Yes, they implemented getDevices() to their app (Espruino WebIDE), but I don't see watchAdvertisements() being used.

My sense of the feedback is that they are potential future additions to the capabilities enabled by these APIs. The goal of this feature is to enable developers to access previously permitted devices without having to prompt the user. watchAdvertisements() is needed since Bluetooth devices can potentially be out of range.

For this initial launch of this feature, I don't plan on incorporating the filtering of devices returned by getDevices(). There would be more work required to determine how these devices can be filtered out, for example should they use the same filter used for requestDevice()? Additionally, since device identifiers are not exposed to sites, there's not a good way to filter for a specific device. Also, as mentioned in the previous message, filtering out devices that are in range would require some more thought on how to implement this, as getDevices() would have to start a scan and wait a certain amount of time to detect any devices nearby. However, I think that these would be good to add to future additions to this API.

A version of watch advertisements for all permitted devices would be a new API that would need to be planned and added to the specification. This can be done in the future as well.

I don't really have a strong opinion on AbortController vs. an explicit unwatchAdvertisements() method. The Web Bluetooth spec did originally have unwatchAdvertisements(), but I updated the specification in March to use AbortController instead after some discussion with Reilly. Both ways of doing this makes sense to me, I don't really see an advantage using one way over the other. There are two other Web Bluetooth APIs that can potentially use AbortController as well. The BluetoothLEScan.stop() is still experimental and not actively being worked on, so that one has flexibility to change to AbortController. The BluetoothRemoteGATTCharacteristic.stopNotifications() is already implemented and shipped with Web Bluetooth, so that one would require more work to change if AbortController is the better choice for cancelling that operation.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/50e5c72c-b47a-4bff-859c-6c6f8b9d0710o%40chromium.org.

[Chris Harrelson]

Ok thanks.

LGTM1!

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/840f51b3-7d9f-4af5-a969-6d0a67dd566eo%40chromium.org.

[Yoav Weiss]

LGTM2

[Mike West]

LGTM3.

[Ajay Rahatekar]

BluetoothDevice.watchAdvertisements() is not planned to be shipped. The chromestatus entry has been updated accordingly.