Abstract

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

Status of This Document

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 changes have been made since the W3C Candidate Recommendation 23 July 2013 Last Call Working Draft 11 February 2014 :

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 Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org ( subscribe , archives ). The Last Call period ends 04 March 24 July 2014. All comments are welcome.

Publication as a Last Call Working Draft 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 is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.

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 .

Table of Contents

1. Introduction

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 Web Notifications [ notifications ] specification. In addition, determining whether vibration is enabled is out of scope for this specification.

2. Conformance

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 MUST , MUST NOT , REQUIRED , SHOULD , SHOULD NOT , RECOMMENDED , MAY , and OPTIONAL in this specification 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.

3. Terminology

The concepts browsing context and spin the event loop are defined in [ HTML5 ].

4. Vibration Interface 

partial interface Navigator {
    boolean vibrate ((unsigned long or sequence<unsigned long>) pattern);
};

The vibrate() method, when invoked, MUST run the algorithm for processing vibration patterns .

The rules for processing vibration patterns are as given in the following algorithm:

  1. Let pattern be the value of the first argument.
  2. If pattern is a list, proceed to the next step. Otherwise run the following substeps:
    1. Let list be an initially empty list, and add pattern to list .
    2. Set pattern to list .
  3. Let max length be an implementation-dependent maximum length of pattern .
    Note
    If the length of a pattern is greater than max length an implementation of this API could consider breaking the request effectively into multiple shorter requests internally to achieve the same effect, rather than ignoring what follows the max length. There are cases, however, where it is appropriate to ignore the pattern exceeding the max length. An example is if the length is so long that it would effectively create a denial of service attack on the user. A web application might also make multiple requests if it is known to the application that the length is too long for some implementations and a possible gap in between patterns is acceptable.
  4. If the length of pattern is greater than max length , truncate pattern , leaving only the first max length entries.
    Note
    If the length of the pattern is even and is not zero, zero then remove the last entry in the pattern will have no effect so an implementation can remove it from the pattern . at this point.
  5. Let max duration be an implementation-dependent maximum duration for a single vibration entry in a pattern .
  6. For each entry in pattern whose value is greater than max duration , set the entry's value to max duration .
  7. If the hidden attribute [ PAGE-VISIBILITY ] is set to true, then return false and terminate these steps.
    Note
    A trusted (also known as privileged) application that integrates closely with the operating system's functionality may vibrate the device even if such an application is not visible at all, and thus may ignore the previous step.
  8. An implementation MAY return false and terminate these steps.
    Note
    For example, an implementation might abort the algorithm because the user has set a preference indicating that pages at a given origin should never be able to vibrate the device, or an implementation might cap the total amount of time a page may cause the device to vibrate and reject requests in excess of this limit.
  9. If there is a pre-existing instance of the processing vibration patterns algorithm running for this browsing context, run the following substeps:
    1. Cancel the pre-existing instance of the processing vibration patterns algorithm, if any.
    2. If pattern is an empty list, or if the device is unable to vibrate, then return true and terminate these steps.
  10. Return true, and then continue running these steps asynchronously.
  11. For each time in pattern , run the following substeps:
    1. If the index of time is even (the first entry has index 0), vibrate the device for time milliseconds.
    2. Otherwise wait for time milliseconds.

When the visibilitychange event [ PAGE-VISIBILITY ] is dispatched at the Document in a browsing context , the user agent MUST cancel the pre-existing instance of the processing vibration patterns algorithm, if any.

5. Examples

This section is non-normative.

In the following example the device will vibrate for 1000 milliseconds (ms):

Example 1 
// vibrate for 1000 ms
navigator.vibrate(1000);
// 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:

Example 2 
navigator.vibrate([50, 100, 150]);

The following example cancels any existing vibrations:

Example 3 
// cancel any existing vibrations
navigator.vibrate(0);
// or alternatively
navigator.vibrate([]);

A. Acknowledgements

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.

B. References

B.1 Normative references

[HTML5]
Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5 . 6 August 2013. 29 April 2014. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/
[PAGE-VISIBILITY]
Jatinder Mann; Arvind Jain. Page Visibility . 14 May 2013. W3C Recommendation. URL: http://www.w3.org/TR/page-visibility/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL . 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/

B.2 Informative references

[notifications]
John Gregg; Anne van Kesteren. Web Notifications . 12 September 2013. W3C Last Call Working Draft. URL: http://www.w3.org/TR/notifications/