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

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.

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

If pattern is a list, proceed to the next step.
Otherwise run the following substeps:

Let list be an initially empty list, and add
pattern to list.

Set pattern to list.

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.

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.

Let max duration be an implementation-dependent maximum
duration for a single vibration entry in a pattern.

For each entry in pattern whose value is greater than
max duration, set the entry's value to max
duration.

Return pattern.

To perform vibration using pattern, run these
steps:

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.

If another instance of the perform vibration algorithm is
already running, run the following substeps:

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

Examples

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

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.