Please check the errata for any errors or issues reported since publication.
The English version of this specification is the only normative version. Non-normative translations may also be available.
Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This specification defines an API that provides access to the vibration mechanism of the hosting device. Vibration is a form of tactile feedback.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
The following editorial changes were made since the W3C Recommendation 10 February 2015 (diff):
This document represents the consensus of the group on the scope and features of the Vibration API. It should be noted that the group is aware of more advanced use cases that cannot be realized using this simpler first version. The intent is to address them in a future revision.
This document was published by the Device and Sensors Working Group as a Recommendation. If you wish to make comments regarding this document, please send them to firstname.lastname@example.org (subscribe, archives). All comments are welcome.
Please see the Working Group's implementation report.
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Process Document.
This section is non-normative.
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 [NOTIFICATIONS] specification. In addition, determining whether vibration is enabled is out of scope for this specification.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL-1], as this specification uses that specification and terminology.
The concepts top-level browsing context and spin the event loop are defined in [HTML5].
typedef (unsigned long or sequence<unsigned long>) VibratePattern;
method, when invoked, MUST run the algorithm for processing vibration patterns.
The rules for processing vibration patterns are as given in the following algorithm:
visible, then return false and terminate these steps.
To validate and normalize a vibration pattern given pattern, run these steps:
To perform vibration using pattern, run these steps:
When the user agent determines that the visibility
state of the
Document of the top-level browsing
context changes, it MUST abort the already running processing
vibration patterns algorithm, if any.
Vibration API is not a source of data on its own and as such is not producing any data possible to consume on the Web. However, it is known that it can serve as a source of events for other APIs. In particular, it is known that certain sensors such as accelerometers or gyroscopes are prone to tiny imperfections during their manufacturing. As such, they provide a fingerprinting surface that can be exploited utilizing the vibration stimuli generated via the Vibration API. In this sense, Vibration API provides an indirect privacy risk, in conjunction with other mechanisms. This can create possibly unexpected privacy risks, including cross-device tracking and communication. Additionally, a device that is vibrating might be visible to external observers and enable physical identification, and possibly tracking of the user.
For these reasons, the user agent SHOULD inform the user when the API is being used and provide a mechanism to disable the API (effectively no-op), on a per-origin basis or globally.
This section is non-normative.
In the following example the device will vibrate for 1000 milliseconds (ms):
// vibrate for 1000 ms navigator.vibrate(1000); // or alternatively navigator.vibrate();
In the following example the pattern will cause the device to vibrate for 50 ms, be still for 100 ms, and then vibrate for 150 ms:
navigator.vibrate([50, 100, 150]);
The following example cancels any existing vibrations:
// cancel any existing vibrations navigator.vibrate(0); // or alternatively navigator.vibrate();
The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas Sicking, and the Mozilla WebAPI team for their contributions, and for providing the WebVibrator prototype as an initial input. Thanks to Anne van Kesteren for suggestions on how to make the specification reusable in other contexts, and to Lukasz Olejnik for the privacy considerations. Finally, thanks to Zhiqiang Zhang for the Simplified Chinese translation.