Vibration API

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, MUST, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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-1], as this specification uses that specification and terminology.

WebIDLtypedef (unsigned long or sequence<unsigned long>) VibratePattern;

partial interface Navigator {
    boolean vibrate (VibratePattern pattern);
};

The vibrate() method steps are to run the processing vibration patterns algorithm. A vibration pattern is represented by a VibratePattern object.

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 document's visibility state is not visible, 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.
4. Perform vibration with this's relevant global object and 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 have the value 10.
3. 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 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 have the value 10000.
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 a global object global and a vibration pattern pattern, run these steps:

1. If global does not have sticky activation, return false and terminate these steps.
2. An implementation MAY return false and terminate these steps.
   Note

   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.
3. 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.
4. Return true, and then continue running these steps asynchronously.
5. 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.

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

The user agent SHOULD employ global rate limiting to restrict the number of vibration requests made within a certain period (e.g., per minute or hour) to prevent excessive use.