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/.
The following editorial changes were made since the W3C Candidate Recommendation 09 September 2014 (diff):
shorthand was added.
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 APIs Working Group as a Proposed Recommendation. This document is intended to become a W3C Recommendation. The W3C Membership and other interested parties are invited to review the document and send comments to firstname.lastname@example.org (subscribe, archives) through 20 January 2015. Advisory Committee Representatives should consult their WBS questionnaires. Note that substantive technical comments were expected during the Last Call review period that ended 24 July 2014.
Please see the Working Group's implementation report.
Publication as a Proposed 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.
By publishing this Proposed Recommendation, W3C expects that the functionality specified in this Proposed Recommendation will not be affected by changes to Web IDL as it proceeds to Recommendation.
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 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 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], as this specification uses that specification and terminology.
The concepts browsing context and spin the event loop are defined in [HTML5].
method, when invoked, MUST run the algorithm
for processing vibration patterns.
The rules for processing vibration patterns are as given in the following algorithm:
hidden attribute [PAGE-VISIBILITY] is set to true,
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:
visibilitychange event [PAGE-VISIBILITY] is dispatched at
Document in a browsing context, the
user agent MUST abort the
already running processing vibration patterns algorithm, if any.
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.