W3C

Vibration API

W3C Last Call Working Draft

This version:
http://www.w3.org/TR/2013/WD-vibration-20130523/
Latest published version:
http://www.w3.org/TR/vibration/
Latest editor's draft:
http://dev.w3.org/2009/dap/vibration/
Previous version:
http://www.w3.org/TR/2012/CR-vibration-20120508/
Editor:
Anssi Kostiainen , Intel

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 changes made since the 08 May 2012 W3C Candidate Recommendation ( 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 realised 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 Candidate Recommendation. 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 ). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 01 July 2012. The Last Call period ends 13 June 2013. All feedback is comments are welcome.

Publication as a Candidate Recommendation 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 Vibration API defines a means for web developers to programmatically provide tactile feedback in the form of vibration. The API is specifically designed to tackle high-value address use cases related to gaming, and that require simple tactile feedback only. Use cases requiring more fine-grained control are out of scope for this specification. In addition, the API is not meant to be used as a generic notification mechanism.

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 , must not MUST NOT , required REQUIRED , should SHOULD , should not SHOULD NOT , recommended RECOMMENDED , may MAY , and optional 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. Vibration Interface Terminology

Navigator implements Vibration

The concepts browsing context ; and All instances of spin the Navigator event loop type are defined to also implement the Vibration in [ HTML5 interface. { }; ].

3.1 4. Methods vibrate Parameter Type Nullable Optional Description time unsigned long ✘ ✘ Vibration time in milliseconds. Return type: void vibrate Parameter Type Nullable Optional Description pattern unsigned long [] ✘ ✘ A vibration pattern represented by a list of time entries. Odd entries represent vibration time in milliseconds, even entries still periods in milliseconds between the vibrations. Return type: void Interface

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

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

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

  1. If the hidden attribute [ PAGE-VISIBILITY ] is set to true, abort these steps. Let pattern be the value of the first argument.
  2. If pattern is 0, or an empty list, cancel the pre-existing instance of the processing vibration patterns algorithm, if any, and abort these steps. 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. Let Set pattern be to list .
  3. If any entry of pattern exceeds an implementation-dependent limit, then the user agent may throw a NotSupportedError exception [ DOM4 ] return false and abort terminate these steps.
  4. If the length of pattern is even, even and is not zero, then remove the last entry in pattern .
  5. If the length of pattern exceeds an implementation dependent implementation-dependent limit, then return false and terminate these steps.
  6. If the user agent may throw a NotSupportedError hidden exception attribute [ DOM4 PAGE-VISIBILITY ] is set to true, then return false and abort terminate these steps. Cancel
    Note
    A trusted (also known as privileged) application that integrates closely with the pre-existing instance of operating system's functionality may vibrate the processing vibration patterns algorithm, device even if any. such an application is not visible at all, and thus may ignore the previous step.
  7. An implementation may MAY abort the algorithm at this point. 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.
  8. Cancel the pre-existing instance of the processing vibration patterns algorithm, if any.
  9. If pattern is an empty list, or if the device does not provide a vibration mechanism (or it is disabled), 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 earliest even first entry has index 0), vibrate the device for time milliseconds.
    2. Otherwise pause [ HTML5 ] wait for time milliseconds.

When the visibilitychange event [ PAGE-VISIBILITY ] is dispatched at the Document , the user agent must run the following steps: If the hidden attribute [ PAGE-VISIBILITY ] is set to true, the user agent must suppress the vibration produced by running the pre-existing instance of the processing vibration patterns algorithm, if any. If the hidden attribute [ PAGE-VISIBILITY ] is set to false, in a browsing context , the user agent must MUST restore the vibration produced by running cancel the pre-existing instance of the processing vibration patterns algorithm, if any. If the device does not provide a vibration mechanism, or it is disabled, the user agent must silently ignore any invocations of the vibrate() method.

4. 5. Examples

This section is non-normative.

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

navigator navigator . vibrate ([
1000 Example 1 ]);
// vibrate for 1000 ms
navigator.vibrate(1000);

// or alternatively
navigator.vibrate([1000]);

In the following example the pattern will cause the device vibrates to vibrate for 1 second, is 50 ms, be still for 0.5 seconds, 100 ms, and vibrates again then vibrate for 2 seconds: 150 ms:

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

The following example cancels any existing vibrations:

navigator .
vibrate 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 in general for their contributions, and for providing the WebVibrator prototype as an initial input.

B. References

B.1 Normative references

[DOM4] Anne van Kesteren; Aryeh Gregor; Ms2ger. DOM4. 5 January 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-dom-20120105/
[HTML5]
Ian Hickson; David Hyatt. Robin Berjon et al. HTML5. HTML5 25 May 2011. . 17 December 2012. W3C Working Draft. (Work in progress.) Candidate Recommendation. URL: http://www.w3.org/TR/html5 http://www.w3.org/TR/html5/
[PAGE-VISIBILITY]
J. Mann; A. Jain. Page Visibility . 26 September 2011. 14 May 2013. W3C Editor's Draft. (Work in progress.) Recommendation. URL: http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html http://www.w3.org/TR/2013/REC-page-visibility-20130514/
[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. IDL 27 September 2011. . 19 April 2012. W3C Working Draft. (Work in progress.) Candidate Recommendation. URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/ http://www.w3.org/TR/2012/CR-WebIDL-20120419/
B.2 Informative references No informative references.