Copyright
© 2015 2016
W3C ® ( MIT , ERCIM
, Keio , Beihang ), All
Rights Reserved. ). 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 http://www.w3.org/TR/.
No The
following editorial changes were brought to the document made since its publication
as a Proposed Recommendation . By publishing this Recommendation,
W3C expects that the functionality
specified in this document will not be affected by changes to Web
IDL as it proceeds to Recommendation. W3C
Recommendation 10 February 2015
( diff ):
This document was published by the Device APIs and Sensors
Working Group as a Proposed Edited
Recommendation. If you wish to make comments regarding this
document, please send them to public-device-apis@w3.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
Publication as a Proposed Edited Recommendation does not imply
endorsement by the W3C Recommendation. It Membership. This is a stable draft document
and may be used as reference material
updated, replaced or cited from another document. W3C 's role in making the
Recommendation obsoleted by other
documents at any time. It is inappropriate to draw
attention to the specification and to promote its widespread
deployment. This enhances the functionality and interoperability of
the Web. 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 14
October 2005 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 and , 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 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;
The vibrate()
method, when invoked, MUST run the algorithm for processing vibration patterns .vibrate
()
The rules for processing vibration patterns are as given in the following algorithm:
vibrate() vibrate
()
method.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 visibilitychange event [
PAGE-VISIBILITY user agent determines
that the
visibility state ] is dispatched
at of the Document
in a of the
top-level browsing
context , the user agent
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);
navigator
// or alternatively
navigator.vibrate([1000]);
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);
navigator
// 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. contexts, and to
Lukasz Olejnik for the privacy considerations. Finally, thanks to
Zhiqiang Zhang for the Simplified Chinese translation.