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 was published by the Device and Sensors Working Group as a Proposed Edited Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to email@example.com (subscribe, archives). W3C Advisory Committee Members are invited to send formal review comments on this Proposed Edited Recommendation to the W3C Team until 18 September 2016. Members of the Advisory Committee will find the appropriate review form for this document by consulting their list of current WBS questionnaires.
Please see the Working Group's implementation report.
Publication as a Proposed Edited Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
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.