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

The following editorial changes were made since the W3C Candidate Recommendation 09 September 2014 (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 realized using this simpler first version. The intent is to address them in a future revision.

Introduction

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.

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.

Terminology

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

Vibration Interface

boolean vibrate()
VibratePattern 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 first method argument of the vibrate() method.
  2. Let valid pattern be the result of passing pattern to validate and normalize.
  3. If the result of running the steps to determine if the document is hidden [[!PAGE-VISIBILITY]] is true, then return false and terminate these steps.
    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.
  4. Perform vibration with valid pattern.

To validate and normalize a vibration pattern given pattern, run these steps:

  1. 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.
  2. Let max length be an implementation-dependent maximum length of pattern.
    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.
  3. If the length of pattern is greater than max length, truncate pattern, leaving only the first max length entries.
    If the length of the pattern is even and not zero then the last entry in the pattern will have no effect so an implementation can remove it from the pattern at this point.
  4. Let max duration be an implementation-dependent maximum duration for a single vibration entry in a pattern.
  5. For each entry in pattern whose value is greater than max duration, set the entry's value to max duration.
  6. Return pattern.

To perform vibration using pattern, run these steps:

  1. An implementation MAY return false and terminate these steps.
    For example, an implementation might abort the algorithm because no vibration hardware is present, 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.
  2. If another instance of the perform vibration algorithm is already running, run the following substeps:
    1. Abort that other instance of the perform vibration algorithm, if any.
    2. If pattern is an empty list, contains a single entry with a value of 0, or if the device is unable to vibrate, then return true and terminate these steps.
  3. Return true, and then continue running these steps asynchronously.
  4. 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 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.

Security and privacy considerations

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. Additionally, a device that is vibrating might be visible to external observers and enable physical tracking of the user.

Examples

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

        // 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: 

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

The following example cancels any existing vibrations: 

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

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. 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.