Vibration API

[anssiko]

こんにちは TAG-さん!

I'm requesting a TAG review of the Vibration API.

This specification defines an API that provides access to the vibration mechanism of the hosting device. Vibration is a form of tactile feedback.

The API is specifically designed to address use cases that require simple tactile feedback only. Use cases requiring more fine-grained control are out of scope for this specification. This API is not meant to be used as a generic notification mechanism. Such use cases may be handled using the Notifications API that has a normative dependency on this specification. In addition, determining whether vibration is enabled is out of scope for this specification.

• Explainer¹ (minimally containing user needs and example code): This feature predates the explainer era, but its MDN entry serves as a good starting point.
• Specification URL: https://w3c.github.io/vibration/ (Why ED? For details on history of this specification, see "You should also know...")
• Tests: https://wpt.live/vibration/
• User research: [url to public summary/results of research]
• Security and Privacy self-review²: Security and Privacy Self-review w3c/vibration#36
• GitHub repo: https://github.com/w3c/vibration
• Primary contacts (and their relationship to the specification):
  • Anssi Kostiainen (@anssiko, Intel, editor, co-chair)
  • Reilly Grant (@reillyeon, Google, co-chair)
• Organization(s)/project(s) driving the specification: Intel, Google, initially Mozilla (currently unsupportive i.e. implementation stubbed out or no-op)
• Key pieces of existing multi-stakeholder (e.g. developers, implementers, civil society) support, review or discussion of this specification: The Working Group is aware of positive feedback from the disabled community Accessibility Checklist w3c/vibration#37 and web developer community.
• Key pieces of multi-implementer support:
  • Chromium comments: enabled by default in Chrome 32, also enabled by default in other Chromium-based browsers per https://caniuse.com/vibration
  • Mozilla comments: Vibration API (Second Edition) mozilla/standards-positions#907
  • WebKit comments: Vibration API (Second Edition) WebKit/standards-positions#267
  • etc...
• External status/issue trackers for this specification (publicly visible, e.g. Chrome Status): https://caniuse.com/vibration, https://chromestatus.com/feature/5698768766763008

Further details:

• I have reviewed the TAG's Web Platform Design Principles
• Relevant time constraints or deadlines: We'd like to discuss TAG review feedback latest at TPAC 2024.
• The group where the work on this specification is currently being done: Devices and Sensors Working Group
• Major unresolved issues with or opposition to this specification: This specification is republished to address a process issue related to an outdated Recommendation.
• This work is being funded by:

You should also know that...

Chrome shipped this API in 2013, following the initial implementation in Firefox in 2012. To prevent unintended use of the feature, Firefox made a change to its implementation in 2016 to gate the feature behind a permission prompt. During 2016-2017 Chrome solicited feedback from users and enabled user activation gating for the feature, first for third-party iframes only, then also for top-level, inspired by conceptually analogous web audio and video autoplay also gated by a user activation. Later, Firefox decided to make the API act as no-op, presumably due to inability to find a satisfactory explicit user consent mechanism, a decision predating user activation gating being incorporated into the specification.

Due to complexity of revising a Recommendation under the old process, TR for this specification did not receive these latest updates informed by implementation experience, but they were incorporated into the Editor's Draft instead. This caused some unfortunate confusion among readers not closely watching the specification. To clear this confusion, supported by reinvigorated interest and process improvements for revising a Recommendation, this API is now being revived on the Recommendation Track to allow bringing the updates from the ED back to TR and to allow for further improvements using the modern streamlined publication flow.

Since the latest published version the Working Group has gathered further implementation experience, added new privacy protections and improved reuse of definitions in other specifications.

The group decided to publish the specification as a new Candidate Recommendation Snapshot to bring updates that align with implementations from the ED to the TR.

Please see the commit history for details and the changes section for an overview of the changes since the latest published version. Diff between the latest published version and the staged snapshot is available at htmldiff.

Thank you for your review!

[jyasskin]

We discussed this last week and settled on the following request:

Given the proposal to obsolete the Vibration REC and 2 browser engines' reluctance to implement it, we wonder if there's another direction that could attract more interoperability. For example, would enough use cases be served if browsers could treat the device they're running on as a gamepad (https://w3c.github.io/gamepad/#gamepadhapticactuator-interface)? We think it would help everyone evaluate this API if the WG would write an explainer for their current direction, including a list of use cases and alternatives that you've considered.

[anssiko]

Thanks for your review!

We consulted the Gamepad API editor to understand whether it'd be feasible to repurpose the current Gamepad API to cater for the Vibration API use cases as suggested. In our discussion we concluded it is not possible. For details, please see the meeting minutes.

For considered alternatives, we've looked at HapticsDevice API proposal that targets haptic-enabled surfaces and gaming controllers. There are a few important areas where that API (that exists in an explainer form only?) differs materially from the Vibration API:

HapticsDevice API defines non-interactive haptic feedback as out of scope, tying haptics into the PointerEvent interface. The Vibration API allows non-interactive feedback after the user has interacted with the page once (sticky activation). Non-interactive feedback has use cases in both gaming and web apps where the feedback is delivered in response to some event happening, not just in response to user interaction that triggers a PointerEvent. Such use cases include e.g. a game where a character bumps into a wall or an app where a long-running process finishes followed by a vibration to inform the user.

Another design consideration where the two APIs differ in a use case impacting way is that the HapticsDevice API supports implementation-defined waveforms (aka Pre-Defined Waveforms) while the Vibration API supports on-off pulses only. The latter provides a consistent experience across platforms, while the former as implementation-defined provides consistency within a one native platform only, but not across multiple platforms.

(We're aware of interesting experiments that create more complex waveforms using the Vibration API on-off pulses as low-level primitives to demonstrate feasibility of consistent waveform generation across platforms. This lowering approach follows the EWM principles.)

Since the Vibration API predates the explainer-era we did not have an explainer handy. We hope this comment addressed your questions and unblocks this review. I've filed w3c/vibration#45 for the explainer and we'll incorporate insights from this review into that document. Thank you!

[martinthomson]

Hi @anssiko, thanks for being so proactive about engagement here.

The TAG looked at this in breakout and we have a few concerns:

We're concerned about the abuse of this API to divert attention in inappropriate situations. We note that you're specifying sticky activation. Are there use cases that support this - rather than transient activation?

For the difference in activation types, we think that sticky activation might not be a good justification for the notification-style use case. If someone isn't engaging with the site, having it vibrate could be annoying. If the goal is to generate a notification, the notification API seems like a much better fit for that. At least with notifications, people are in control of how they are notified (sound, visual, vibration, or combinations).

There is a good analogy between this and audio, in that both might be engaged in a similar way and disabled with similar controls. However, have you considered adding a stronger normative requirement that UAs should be able to turn it off? It's not as easy to turn off a vibration with physical controls as it is with sound.

Security/privacy considerations don't treat annoyance as a problem. Interruptions is a privacy issue you should consider addressing. We like that the vibrations only activate when the page is visible, but that seems like something that should be directly addressed as a mitigation for that issue. A transient activation requirement might help further.

Security considerations should require that accelerometers and gyroscopes are disabled for other origins when vibrating.

[anssiko]

Thanks for your careful review of this API! To quickly answer the question while you're breakout-ting:

We note that you're specifying sticky activation. Are there use cases that support this - rather than transient activation?

I believe the following and other similar use cases do require a sticky activation:

Non-interactive feedback has use cases in both gaming and web apps where the feedback is delivered in response to some event happening, not just in response to user interaction that triggers a PointerEvent. Such use cases include e.g. a game where a character bumps into a wall or an app where a long-running process finishes followed by a vibration to inform the user.

[martinthomson]

That use cases suggests that maybe there is a state that exists between sticky and transient. That use case hardly ever involves a complete lack of interaction, but maybe ~4s (what I believe transient holds for) is not sufficient for that.

Edit to note that @hober suggests that maybe sticky activation might be fixed to reduce the potential for annoyance. For instance, deactivating it after any of: 30 minutes, sleep, the window losing visibility for more than 10s, etc.. (all numbers negotiable).

[anssiko]

Thank you for resolving this review.

If an implementation wants to deactivate sticky activation to reduce annoyance, step 2 in the perform vibration algorithm provides an escape hatch for that. Examples provided by @hober are excellent.