├── .github └── workflows │ └── auto-publish.yml ├── .pr-preview.json ├── CONTRIBUTING.md ├── LICENSE.md ├── README.md ├── index.html ├── releases ├── CR.html ├── CR2-diff.html ├── CR2.html ├── CR2.src.html ├── CR3-diff.html ├── CR3.html ├── CR3.src.html ├── FPWD.html ├── LC.html ├── LC2.html ├── LC2.src.html ├── LC3.html ├── LC3.src.html ├── LC4-diff.html ├── LC4.html ├── LC4.src.html ├── Overview-diff.html ├── PER-diff.html ├── PER.html ├── PER.src.html ├── PR-diff.html ├── PR.html └── PR.src.html └── w3c.json /.github/workflows/auto-publish.yml: -------------------------------------------------------------------------------- 1 | # https://github.com/w3c/spec-prod/blob/main/docs/examples.md#use-different-respecconfig-when-deploying-to-w3c 2 | 3 | name: CI 4 | on: 5 | pull_request: {} 6 | push: 7 | branches: [gh-pages] 8 | jobs: 9 | main: 10 | name: Build, Validate and Deploy 11 | runs-on: ubuntu-latest 12 | steps: 13 | - uses: actions/checkout@v2 14 | - uses: w3c/spec-prod@v2 15 | with: 16 | TOOLCHAIN: respec 17 | W3C_ECHIDNA_TOKEN: ${{ secrets.ECHIDNA_TOKEN }} 18 | W3C_WG_DECISION_URL: https://lists.w3.org/Archives/Public/public-device-apis/2021May/0008.html 19 | # Publish to w3.org/TR as a Candidate Recommendation Draft (CRD) 20 | W3C_BUILD_OVERRIDE: | 21 | specStatus: CRD 22 | shortName: vibration -------------------------------------------------------------------------------- /.pr-preview.json: -------------------------------------------------------------------------------- 1 | { 2 | "src_file": "index.html", 3 | "type": "respec" 4 | } 5 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Contributions to this repository are intended to become part of Recommendation-track documents governed by the 2 | [W3C Patent Policy](http://www.w3.org/Consortium/Patent-Policy-20040205/) and 3 | [Document License](http://www.w3.org/Consortium/Legal/copyright-documents). To make substantive contributions to specifications, you must either participate 4 | in the relevant W3C Working Group or make a non-member patent licensing commitment. 5 | 6 | If you are not the sole contributor to a contribution (pull request), please identify all 7 | contributors in the pull request comment. 8 | 9 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 10 | 11 | ``` 12 | +@github_username 13 | ``` 14 | 15 | If you added a contributor by mistake, you can remove them in a comment with: 16 | 17 | ``` 18 | -@github_username 19 | ``` 20 | 21 | If you are making a pull request on behalf of someone else but you had no part in designing the 22 | feature, you can remove yourself with the above syntax. 23 | 24 | # Tests 25 | 26 | For normative changes, a corresponding 27 | [web-platform-tests](https://github.com/web-platform-tests/wpt) PR is highly appreciated. Typically, 28 | both PRs will be merged at the same time. Note that a test change that contradicts the spec should 29 | not be merged before the corresponding spec change. If testing is not practical, please explain why 30 | and if appropriate [file a web-platform-tests issue](https://github.com/web-platform-tests/wpt/issues/new) 31 | to follow up later. Add the `type:untestable` or `type:missing-coverage` label as appropriate. 32 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All documents in this Repository are licensed by contributors 2 | under the 3 | [W3C Document License](http://www.w3.org/Consortium/Legal/copyright-documents). 4 | 5 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Vibration API 2 | 3 | This repository contains the [Vibration API](https://w3c.github.io/vibration/) 4 | specification. -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Vibration API 6 | 7 | 8 | 11 | 45 | 46 | 47 |
48 | This specification defines an API that provides access to the vibration 49 | mechanism of the hosting device. Vibration is a form of tactile feedback. 50 |
51 |
52 |

53 | This document represents the consensus of the group on the scope and 54 | features of the Vibration API. It should be noted that the group is 55 | aware of more advanced use cases that cannot be realized using this 56 | simpler first version. The intent is to address them in a future 57 | revision. 58 |

59 |

60 | A history of changes from previous version is provided. 61 |

62 |
63 |
64 |

65 | Introduction 66 |

67 |

68 | The API is specifically designed to address use cases that require 69 | simple tactile feedback only. Use cases requiring more fine-grained 70 | control are out of scope for this specification. This API is not meant 71 | to be used as a generic notification mechanism. Such use cases may be 72 | handled using the Notifications API [[NOTIFICATIONS]] 73 | specification. In addition, determining whether vibration is enabled is 74 | out of scope for this specification. 75 |

76 |
77 |
78 |

79 | This specification defines conformance criteria that apply to a single 80 | product: the user agent that implements the 81 | interfaces that it contains. 82 |

83 |

84 | Implementations that use ECMAScript to implement the APIs defined in 85 | this specification must implement them in a manner consistent with the 86 | ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL-1]], 87 | as this specification uses that specification and terminology. 88 |

89 |
90 |
91 |

92 | Vibration Interface 93 |

94 | 
 95 |         typedef (unsigned long or sequence<unsigned long>) VibratePattern;
 96 | 
 97 |         partial interface Navigator {
 98 |             boolean vibrate (VibratePattern pattern);
 99 |         };
100 |
101 |

102 | The vibrate() method 103 | steps are to run the processing vibration patterns algorithm. 104 | A vibration pattern is represented by a 105 | VibratePattern object. 106 |

107 |

108 | The rules for processing vibration patterns are as given in 109 | the following algorithm: 110 |

111 |
    112 |
  1. Let pattern be the first method argument of the 113 | vibrate() method. 114 |
    2. 115 |
  2. Let valid pattern be the result of passing 116 | pattern to validate and normalize. 117 |
    3. 118 |
  3. If the document's [=Document/visibility state=] is not 119 | visible, then return false and terminate these steps. 120 |
    121 | A trusted (also known as privileged) application that integrates 122 | closely with the operating system's functionality may vibrate the 123 | device even if such an application is not visible at all, and thus 124 | may ignore the previous step. 125 |
    126 |
    4. 127 |
  4. 128 | Perform vibration with this's relevant global object 129 | and valid pattern. 130 |
    5. 131 |
132 |

133 | To validate and normalize a vibration pattern given 134 | pattern, run these steps: 135 |

136 |
    137 |
  1. If pattern is a list, proceed to the next step. 138 | Otherwise run the following substeps: 139 |
      140 |
    1. Let list be an initially empty list, and add 141 | pattern to list. 142 |
      2. 143 |
    2. Set pattern to list. 144 |
      3. 145 |
    146 |
    2. 147 |
  2. Let max length have the value 10. 148 |
    3. 149 |
  3. If the length of pattern is greater than max 150 | length, truncate pattern, leaving only the first 151 | max length entries. 152 |
    153 | If the length of the pattern is even and not zero then 154 | the last entry in the pattern will have no effect so an 155 | implementation can remove it from the pattern at this 156 | point. 157 |
    158 |
    4. 159 |
  4. Let max duration have the value 10000. 160 |
    5. 161 |
  5. For each entry in pattern whose value is greater than 162 | max duration, set the entry's value to max 163 | duration. 164 |
    6. 165 |
  6. Return pattern. 166 |
    7. 167 |
168 |

169 | To perform vibration using a global object 170 | global and a vibration pattern pattern, 171 | run these steps: 172 |

173 |
    174 |
  1. 175 | If global does not have sticky activation, 176 | return false and terminate these steps. 177 |
    2. 178 |
  2. An implementation MAY return false and terminate these steps. 179 |
    180 | For example, an implementation might abort the algorithm because no 181 | vibration hardware is present, the user has set a preference 182 | indicating that pages at a given origin should never be able to 183 | vibrate the device, or an implementation might cap the total amount 184 | of time a page may cause the device to vibrate and reject requests 185 | in excess of this limit. 186 |
    187 |
    3. 188 |
  3. If another instance of the perform vibration algorithm is 189 | already running, run the following substeps: 190 |
      191 |
    1. Abort that other instance of the perform vibration 192 | algorithm, if any. 193 |
      2. 194 |
    2. If pattern is an empty list, contains a single entry 195 | with a value of 0, or if the device is unable to vibrate, then 196 | return true and terminate these steps. 197 |
      3. 198 |
    199 |
    4. 200 |
  4. Return true, and then continue running these steps asynchronously. 201 |
    5. 202 |
  5. For each time in pattern, run the following 203 | substeps: 204 |
      205 |
    1. If the index of time is even (the first entry has 206 | index 0), vibrate the device for time milliseconds. 207 |
      2. 208 |
    2. Otherwise wait for time milliseconds. 209 |
      3. 210 |
    211 |
    6. 212 |
213 |

214 | When the user agent determines that 215 | the [=Document/visibility state=] of 216 | the Document of the top-level browsing 217 | context changes, it MUST abort the already running processing 218 | vibration patterns algorithm, if any. 219 |

220 |
221 |
222 |

223 | Security and privacy considerations 224 |

225 |

226 | Vibration API is not a source of data on its own and as such is not 227 | producing any data possible to consume on the Web. However, it is known 228 | that it can serve as a source of events for other APIs. In particular, 229 | it is known that certain sensors such as accelerometers or gyroscopes 230 | are prone to tiny imperfections during their manufacturing. As such, 231 | they provide a fingerprinting surface that can be exploited utilizing 232 | the vibration stimuli generated via the Vibration API. In this sense, 233 | Vibration API provides an indirect privacy risk, in conjunction with 234 | other mechanisms. This can create possibly unexpected privacy risks, 235 | including cross-device tracking and communication. Additionally, a 236 | device that is vibrating might be visible to external observers and 237 | enable physical identification, and possibly tracking of the user. 238 |

239 |

240 | For these reasons, the user agent MAY inform the user when 241 | the API is being used and provide a mechanism to disable the API 242 | (effectively no-op), on a per-origin basis or globally. 243 |

244 |

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

249 |
250 |
251 |

252 | Examples 253 |

254 |

255 | In the following example the device will vibrate for 1000 milliseconds 256 | (ms): 257 |

258 | 
259 |         // vibrate for 1000 ms
260 |         navigator.vibrate(1000);
261 |         
262 |         // or alternatively
263 |         navigator.vibrate([1000]);
264 |
265 |

266 | In the following example the pattern will cause the device to vibrate 267 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 268 |

269 | 
270 |         navigator.vibrate([50, 100, 150]);
271 |
272 |

273 | The following example cancels any existing vibrations: 274 |

275 | 
276 |           // cancel any existing vibrations
277 |           navigator.vibrate(0);
278 |           
279 |           // or alternatively
280 |           navigator.vibrate([]);
281 |
282 |
283 |
284 |

285 | Acknowledgements 286 |

287 |

288 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 289 | Sicking, and the Mozilla WebAPI team for their contributions, and for 290 | providing the WebVibrator prototype as an initial input. Thanks to Anne 291 | van Kesteren for suggestions on how to make the specification reusable 292 | in other contexts, and to Lukasz Olejnik for the privacy 293 | considerations. Finally, thanks to Zhiqiang Zhang for the Simplified 294 | Chinese translation. 295 |

296 |
297 |
298 |

299 | Changes 300 |

301 |

302 | Changes since W3C Recommendation 18 October 2016: 303 |

304 | 316 |

317 | Other changes that do not functionally affect interpretation of the document: 318 |

319 | 322 |
323 |
324 |
325 | 326 | 327 | -------------------------------------------------------------------------------- /releases/CR.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Vibration API 5 | 6 | 7 | 8 | 474 |

W3C

Vibration API

W3C Candidate Recommendation 08 May 2012

This version:
http://www.w3.org/TR/2012/CR-vibration-20120508/
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/WD-vibration-20120202/
Editor:
Anssi Kostiainen, Nokia
475 |

Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

476 |

Abstract

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

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

480 |

481 | This document represents the consensus of the group on the scope and features of the 482 | Vibration API. It should be noted that the group is aware of more advanced use cases that cannot 483 | be realised using this simpler first version. The intent is to address them in a future revision. 484 |

485 |

This document was published by the Device APIs Working Group as a Candidate Recommendation. 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. All feedback is welcome.

Publication as a Candidate Recommendation 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 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

486 | 487 | 488 | 489 |
490 |

1. Introduction

This section is non-normative.

491 |

492 | The Vibration API defines a means for web developers to 493 | programmatically provide tactile feedback in the form of vibration. The 494 | API is designed to tackle high-value use cases related to gaming, and 495 | is not meant to be used as a generic notification mechanism. 496 |

497 |
498 | 499 |

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.

500 |

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

501 | 502 |

503 | This specification defines conformance criteria that apply to a single 504 | product: the user agent that implements the 505 | interfaces that it contains. 506 |

507 |

508 | Implementations that use ECMAScript to implement the APIs defined in 509 | this specification must implement them in a manner consistent with the 510 | ECMAScript Bindings defined in the Web IDL specification [WEBIDL], 511 | as this specification uses that specification and terminology. 512 |

513 |
514 | 515 |
516 |

3. Vibration Interface

517 | 
Navigator implements Vibration;

All instances of the Navigator type are defined to also implement the Vibration interface.

518 | 
interface Vibration {
519 |     void vibrate (unsigned long time);
520 |     void vibrate (unsigned long[] pattern);
521 | };
522 |

3.1 Methods

vibrate
523 | 524 |
ParameterTypeNullableOptionalDescription
timeunsigned long✘✘ 525 | Vibration time in milliseconds. 526 |
Return type: void
vibrate
527 | 528 |
ParameterTypeNullableOptionalDescription
patternunsigned long[]✘✘ 529 | A vibration pattern represented by a list of time entries. 530 | Odd entries represent vibration time in milliseconds, even 531 | entries still periods in milliseconds between the vibrations. 532 |
Return type: void
533 | 534 |

535 | The vibrate() method, when invoked, must run the algorithm 536 | for processing vibration patterns. 537 |

538 |

539 | The rules for processing vibration patterns are as given in 540 | the following algorithm: 541 |

542 |
    543 | 549 |
  1. 550 | If the 551 | 552 | hidden attribute [PAGE-VISIBILITY] is set to true, 553 | abort these steps. 554 |
    2. 555 | 558 |
  2. 559 | Let pattern be the value of the first argument. 560 |
    3. 561 |
  3. 562 | If pattern is 0, or an empty list, cancel the pre-existing 563 | instance of the processing vibration patterns algorithm, if 564 | any, and abort these steps. 565 |
    4. 566 |
  4. 567 | If pattern is a list, proceed to the next step. 568 | Otherwise run the following substeps: 569 |
      570 |
    1. 571 | Let list be an initially empty list, and add 572 | pattern to list. 573 |
      2. 574 |
    2. 575 | Let pattern be list. 576 |
      3. 577 |
    578 |
    5. 579 |
  5. 580 | If any entry of pattern exceeds an 581 | implementation-dependent limit, then the 582 | user agent may throw a 583 | NotSupportedError exception [DOM4] and abort these 584 | steps. 585 |
    6. 586 |
  6. 587 | If the length of pattern is even, then remove the last 588 | entry in pattern. 589 |
    7. 590 |
  7. 591 | If the length of pattern exceeds an implementation 592 | dependent limit, the user agent 593 | may throw a NotSupportedError exception [DOM4] and 594 | abort these steps. 595 |
    8. 596 |
  8. 597 | Cancel the pre-existing instance of the processing vibration 598 | patterns algorithm, if any. 599 |
    9. 600 |
  9. 601 | An implementation may abort the algorithm at this point. 602 |
    603 | For example, an implementation might abort the 604 | algorithm because the user has set a preference indicating that 605 | pages at a given origin should never be able to vibrate the device, 606 | or an implementation might cap the total amount of time a page may 607 | cause the device to vibrate and reject requests in excess of this 608 | limit. 609 |
    610 |
    10. 611 |
  10. 612 | For each time in pattern, run the following 613 | substeps: 614 |
      615 |
    1. 616 | If the index of time is even (the earliest even entry 617 | has index 0), vibrate the device for time 618 | milliseconds. 619 |
      2. 620 |
    2. 621 | Otherwise 622 | 623 | pause [HTML5] for time milliseconds. 624 |
      3. 625 |
    626 |
    11. 627 |
628 |

629 | When the 630 | 631 | visibilitychange event [PAGE-VISIBILITY] is dispatched at 632 | the Document, the user 633 | agent must run the following steps: 634 |

635 |
    636 |
  1. 637 | If the 638 | hidden attribute [PAGE-VISIBILITY] is set to true, 639 | the user agent must suppress 640 | the vibration produced by running the pre-existing instance of the 641 | processing vibration patterns algorithm, if any. 642 |
    2. 643 |
  2. 644 | If the 645 | hidden attribute [PAGE-VISIBILITY] is set to false, 646 | the user agent must restore 647 | the vibration produced by running the pre-existing instance of the processing vibration 648 | patterns algorithm, if any. 649 |
    3. 650 |
651 |

652 | If the device does not provide a vibration mechanism, or it is 653 | disabled, the user agent must 654 | silently ignore any invocations of the vibrate() method. 655 |

656 |
657 | 658 |
659 |

4. Examples

This section is non-normative.

660 |

661 | In the following example the device vibrates for 1 second: 662 |

663 | 
// vibrate for 1 second
664 | navigator.vibrate(1000);
665 | 
666 | // or alternatively
667 | navigator.vibrate([1000]);
668 |
669 |

670 | In the following example the device vibrates for 1 second, is still for 671 | 0.5 seconds, and vibrates again for 2 seconds: 672 |

673 |
674 | 
navigator.vibrate([1000, 500, 2000]);
675 |
676 |

677 |

678 | The following example cancels any existing vibrations: 679 |

680 |
681 | 
navigator.vibrate(0);
682 | 
683 | // or alternatively
684 | navigator.vibrate([]);
685 |
686 |
687 |
688 |

A. Acknowledgements

689 |

690 | The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and 691 | the Mozilla WebAPI team in general for providing the WebVibrator 692 | prototype as an initial input. 693 |

694 |
695 | 696 | 697 |

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/ 698 |
[HTML5]
Ian Hickson; David Hyatt. HTML5. 25 May 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5 699 |
[PAGE-VISIBILITY]
J. Mann; A. Jain. Page Visibility. 26 September 2011. W3C Editor's Draft. (Work in progress.) URL: http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html 700 |
[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 701 |
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/ 702 |

B.2 Informative references

No informative references.

-------------------------------------------------------------------------------- /releases/CR2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Vibration API 5 | 6 | 7 | 8 | 425 | 426 |
427 |

428 | 429 | W3C 430 | 431 |

432 |

Vibration API

433 | 434 |

W3C Candidate Recommendation

435 |
436 | 437 |
This version:
438 |
http://www.w3.org/TR/2013/CR-vibration-20130723/
439 |
Latest published version:
440 |
http://www.w3.org/TR/vibration/
441 | 442 | 443 |
Latest editor's draft:
444 |
http://dev.w3.org/2009/dap/vibration/
445 | 446 | 447 | 448 | 449 | 450 |
Previous version:
451 |
http://www.w3.org/TR/2013/WD-vibration-20130523/
452 | 453 | 454 |
Editor:
455 |
Anssi Kostiainen, Intel 456 |
457 | 458 | 459 | 460 |
461 | 462 | 463 | 464 | 465 | 466 |

467 | Copyright © 468 | 2013 469 | 470 | W3C® 471 | (MIT, 472 | ERCIM, 473 | Keio, Beihang), All Rights Reserved. 474 | W3C liability, 475 | trademark and 476 | document use rules apply. 477 |

478 | 479 | 480 |
481 |
482 |

Abstract

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

Status of This Document

486 | 487 | 488 | 489 |

490 | This section describes the status of this document at the time of its publication. Other 491 | documents may supersede this document. A list of current W3C publications and the latest revision 492 | of this technical report can be found in the W3C technical reports 493 | index at http://www.w3.org/TR/. 494 |

495 | 496 |

497 | The following changes 498 | (disposition of comments, 499 | redline) have been made 500 | since the 501 | W3C Last Call Working Draft 23 May 2013: 502 |

503 | 516 |

517 | Before this specification 518 | exits Candidate Recommendation, two or more independent deployed 519 | implementations must demonstrate interoperability of each 520 | feature. No features have been marked as 'at risk'. 521 | The group will create an Implementation 522 | Report. 523 |

524 |

525 | This document represents the consensus of the group on the scope and 526 | features of the Vibration API. It should be noted that the group is 527 | aware of more advanced use cases that cannot be realized using this 528 | simpler first version. The intent is to address them in a future 529 | revision. 530 |

531 | 532 |

533 | This document was published by the Device APIs Working Group as a Candidate Recommendation. 534 | 535 | This document is intended to become a W3C Recommendation. 536 | 537 | 538 | If you wish to make comments regarding this document, please send them to 539 | public-device-apis@w3.org 540 | (subscribe, 541 | archives). 542 | 543 | 544 | 545 | W3C publishes a Candidate Recommendation to indicate that the document is believed 546 | to be stable and to encourage implementation by the developer community. This 547 | Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 548 | 18 September 2013. 549 | 550 | 551 | All comments are welcome.

552 | 553 | 554 |

555 | Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. 556 | This is a draft document and may be updated, replaced or obsoleted by other documents at 557 | any time. It is inappropriate to cite this document as other than work in progress. 558 |

559 | 560 | 561 |

562 | 563 | This document was produced by a group operating under the 564 | 565 | 5 February 2004 W3C Patent Policy. 566 | 567 | 568 | 569 | 570 | 571 | W3C maintains a public list of any patent disclosures 572 | 573 | made in connection with the deliverables of the group; that page also includes instructions for 574 | disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains 575 | Essential Claim(s) must disclose the 576 | information in accordance with section 577 | 6 of the W3C Patent Policy. 578 | 579 | 580 |

581 | 582 | 583 | 584 | 585 |

Table of Contents

586 | 587 | 588 | 589 |
590 |

1. Introduction

This section is non-normative.

591 |

592 | The API is specifically designed to address use cases that require 593 | simple tactile feedback only. Use cases requiring more fine-grained 594 | control are out of scope for this specification. This API is not meant 595 | to be used as a generic notification mechanism. Such use cases may be 596 | handled using the Web Notifications [notifications] 597 | specification. In addition, determining whether vibration is enabled 598 | is out of scope for this specification. 599 |

600 |
601 | 602 |

2. Conformance

603 |

604 | As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, 605 | and notes in this specification are non-normative. Everything else in this specification is 606 | normative. 607 |

608 |

609 | The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, 610 | and OPTIONAL in this specification are to be interpreted as described in [RFC2119]. 611 |

612 | 613 |

614 | This specification defines conformance criteria that apply to a single 615 | product: the user agent that implements the 616 | interfaces that it contains. 617 |

618 |

619 | Implementations that use ECMAScript to implement the APIs defined in 620 | this specification must implement them in a manner consistent with the 621 | ECMAScript Bindings defined in the Web IDL specification [WEBIDL], 622 | as this specification uses that specification and terminology. 623 |

624 |
625 | 626 |
627 |

3. Terminology

628 |

629 | The concepts 630 | browsing context and 631 | 632 | spin the event loop are defined in [HTML5]. 633 |

634 |
635 | 636 |
637 |

4. Vibration Interface

638 | 
partial interface Navigator {
639 |     boolean vibrate ((unsigned long or sequence<unsigned long>) pattern);
640 | };
641 | 642 |

643 | The vibrate() 644 | method, when invoked, MUST run the algorithm 645 | for processing vibration patterns. 646 |

647 |

648 | The rules for processing vibration patterns are as given in 649 | the following algorithm: 650 |

651 |
    652 |
  1. 653 | Let pattern be the value of the first argument. 654 |
    2. 655 |
  2. 656 | If pattern is a list, proceed to the next step. 657 | Otherwise run the following substeps: 658 |
      659 |
    1. 660 | Let list be an initially empty list, and add 661 | pattern to list. 662 |
      2. 663 |
    2. 664 | Set pattern to list. 665 |
      3. 666 |
    667 |
    3. 668 |
  3. 669 | If the length of pattern exceeds an 670 | implementation-dependent limit, then return false and terminate 671 | these steps. 672 |
    4. 673 |
  4. 674 | If the length of pattern is even and is not zero, then 675 | remove the last entry in pattern. 676 |
    5. 677 |
  5. 678 | If any entry of pattern exceeds an 679 | implementation-dependent limit, then return false and terminate 680 | these steps. 681 |
    6. 682 |
  6. 683 | If the 684 | 685 | hidden attribute [PAGE-VISIBILITY] is set to true, 686 | then return false and terminate these steps. 687 |
    Note
    688 | A trusted (also known as privileged) application that integrates 689 | closely with the operating system's functionality may vibrate the 690 | device even if such an application is not visible at all, and thus 691 | may ignore the previous step. 692 |
    693 |
    7. 694 |
  7. 695 | An implementation MAY return false and terminate these steps. 696 |
    Note
    697 | For example, an implementation might abort the 698 | algorithm because the user has set a preference indicating that 699 | pages at a given origin should never be able to vibrate the device, 700 | or an implementation might cap the total amount of time a page may 701 | cause the device to vibrate and reject requests in excess of this 702 | limit. 703 |
    704 |
    8. 705 |
  8. 706 | Cancel the pre-existing instance of the processing vibration 707 | patterns algorithm, if any. 708 |
    9. 709 |
  9. 710 | If pattern is an empty list, or if the device does 711 | not provide a vibration mechanism (or it is disabled), then return 712 | true and terminate these steps. 713 |
    10. 714 |
  10. 715 | Return true, and then continue running these steps asynchronously. 716 |
    11. 717 |
  11. 718 | For each time in pattern, run the following 719 | substeps: 720 |
      721 |
    1. 722 | If the index of time is even (the first entry has 723 | index 0), vibrate the device for time milliseconds. 724 |
      2. 725 |
    2. 726 | Otherwise wait for time milliseconds. 727 |
      3. 728 |
    729 |
    12. 730 |
731 |

732 | When the 733 | 734 | visibilitychange event [PAGE-VISIBILITY] is dispatched at 735 | the Document in a browsing context, the 736 | user agent MUST cancel the 737 | pre-existing instance of the processing vibration patterns 738 | algorithm, if any. 739 |

740 |
741 | 742 |
743 |

5. Examples

This section is non-normative.

744 |

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

Example 1
// vibrate for 1000 ms
747 | navigator.vibrate(1000);
748 | 
749 | // or alternatively
750 | navigator.vibrate([1000]);
751 |

752 | In the following example the pattern will cause the device to vibrate 753 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 754 |

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

757 |

758 | The following example cancels any existing vibrations: 759 |

760 |
Example 3
// cancel any existing vibrations
761 | navigator.vibrate(0);
762 | 
763 | // or alternatively
764 | navigator.vibrate([]);
765 |
766 |
767 |

A. Acknowledgements

768 |

769 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 770 | Sicking, and the Mozilla WebAPI team for their contributions, and for 771 | providing the WebVibrator prototype as an initial input. 772 |

773 |
774 | 775 | 776 |

B. References

B.1 Normative references

[HTML5]
Robin Berjon et al. HTML5. 17 December 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/ 777 |
[PAGE-VISIBILITY]
Jatinder Mann; Arvind Jain. Page Visibility. 14 May 2013. W3C Recommendation. URL: http://www.w3.org/TR/page-visibility/ 778 |
[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 779 |
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/ 780 |

B.2 Informative references

[notifications]
Anne van Kesteren; John Gregg. Web Notifications. 14 June 2012. W3C Working Draft. URL: http://www.w3.org/TR/notifications/ 781 |
782 | -------------------------------------------------------------------------------- /releases/CR2.src.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Vibration API 5 | 6 | 7 | 31 | 32 | 33 |
34 | This specification defines an API that provides access to the vibration 35 | mechanism of the hosting device. Vibration is a form of tactile feedback. 36 |
37 | 38 |
39 |

40 | The following changes 41 | (disposition of comments, 42 | redline) have been made 43 | since the 44 | W3C Last Call Working Draft 23 May 2013: 45 |

46 | 59 |

60 | Before this specification 61 | exits Candidate Recommendation, two or more independent deployed 62 | implementations must demonstrate interoperability of each 63 | feature. No features have been marked as 'at risk'. 64 | The group will create an Implementation 65 | Report. 66 |

67 |

68 | This document represents the consensus of the group on the scope and 69 | features of the Vibration API. It should be noted that the group is 70 | aware of more advanced use cases that cannot be realized using this 71 | simpler first version. The intent is to address them in a future 72 | revision. 73 |

74 |
75 | 76 |
77 |

Introduction

78 |

79 | The API is specifically designed to address use cases that require 80 | simple tactile feedback only. Use cases requiring more fine-grained 81 | control are out of scope for this specification. This API is not meant 82 | to be used as a generic notification mechanism. Such use cases may be 83 | handled using the Web Notifications [[notifications]] 84 | specification. In addition, determining whether vibration is enabled 85 | is out of scope for this specification. 86 |

87 |
88 | 89 |
90 |

91 | This specification defines conformance criteria that apply to a single 92 | product: the user agent that implements the 93 | interfaces that it contains. 94 |

95 |

96 | Implementations that use ECMAScript to implement the APIs defined in 97 | this specification must implement them in a manner consistent with the 98 | ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], 99 | as this specification uses that specification and terminology. 100 |

101 |
102 | 103 |
104 |

Terminology

105 |

106 | The concepts 107 | browsing context and 108 | 109 | spin the event loop are defined in [[!HTML5]]. 110 |

111 |
112 | 113 |
114 |

Vibration Interface

115 |
116 |
boolean vibrate()
117 |
118 |
119 |
(unsigned long or sequence<unsigned long>) pattern
120 |
121 |
122 |
123 |
124 | 125 |

126 | The vibrate() 127 | method, when invoked, MUST run the algorithm 128 | for processing vibration patterns. 129 |

130 |

131 | The rules for processing vibration patterns are as given in 132 | the following algorithm: 133 |

134 |
    135 |
  1. 136 | Let pattern be the value of the first argument. 137 |
    2. 138 |
  2. 139 | If pattern is a list, proceed to the next step. 140 | Otherwise run the following substeps: 141 |
      142 |
    1. 143 | Let list be an initially empty list, and add 144 | pattern to list. 145 |
      2. 146 |
    2. 147 | Set pattern to list. 148 |
      3. 149 |
    150 |
    3. 151 |
  3. 152 | If the length of pattern exceeds an 153 | implementation-dependent limit, then return false and terminate 154 | these steps. 155 |
    4. 156 |
  4. 157 | If the length of pattern is even and is not zero, then 158 | remove the last entry in pattern. 159 |
    5. 160 |
  5. 161 | If any entry of pattern exceeds an 162 | implementation-dependent limit, then return false and terminate 163 | these steps. 164 |
    6. 165 |
  6. 166 | If the 167 | 168 | hidden attribute [[!PAGE-VISIBILITY]] is set to true, 169 | then return false and terminate these steps. 170 |
    171 | A trusted (also known as privileged) application that integrates 172 | closely with the operating system's functionality may vibrate the 173 | device even if such an application is not visible at all, and thus 174 | may ignore the previous step. 175 |
    176 |
    7. 177 |
  7. 178 | An implementation MAY return false and terminate these steps. 179 |
    180 | For example, an implementation might abort the 181 | algorithm because the user has set a preference indicating that 182 | pages at a given origin should never be able to vibrate the device, 183 | or an implementation might cap the total amount of time a page may 184 | cause the device to vibrate and reject requests in excess of this 185 | limit. 186 |
    187 |
    8. 188 |
  8. 189 | Cancel the pre-existing instance of the processing vibration 190 | patterns algorithm, if any. 191 |
    9. 192 |
  9. 193 | If pattern is an empty list, or if the device does 194 | not provide a vibration mechanism (or it is disabled), then return 195 | true and terminate these steps. 196 |
    10. 197 |
  10. 198 | Return true, and then continue running these steps asynchronously. 199 |
    11. 200 |
  11. 201 | For each time in pattern, run the following 202 | substeps: 203 |
      204 |
    1. 205 | If the index of time is even (the first entry has 206 | index 0), vibrate the device for time milliseconds. 207 |
      2. 208 |
    2. 209 | Otherwise wait for time milliseconds. 210 |
      3. 211 |
    212 |
    12. 213 |
214 |

215 | When the 216 | 217 | visibilitychange event [[!PAGE-VISIBILITY]] is dispatched at 218 | the Document in a browsing context, the 219 | user agent MUST cancel the 220 | pre-existing instance of the processing vibration patterns 221 | algorithm, if any. 222 |

223 |
224 | 225 |
226 |

Examples

227 |

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

230 |         // vibrate for 1000 ms
231 |         navigator.vibrate(1000);
232 |         
233 |         // or alternatively
234 |         navigator.vibrate([1000]);
235 |
236 |

237 | In the following example the pattern will cause the device to vibrate 238 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 239 |

240 | 
241 |         navigator.vibrate([50, 100, 150]);
242 |
243 |

244 |

245 | The following example cancels any existing vibrations: 246 |

247 | 
248 |           // cancel any existing vibrations
249 |           navigator.vibrate(0);
250 |           
251 |           // or alternatively
252 |           navigator.vibrate([]);
253 |
254 |
255 |
256 |

Acknowledgements

257 |

258 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 259 | Sicking, and the Mozilla WebAPI team for their contributions, and for 260 | providing the WebVibrator prototype as an initial input. 261 |

262 |
263 | 264 | 265 | -------------------------------------------------------------------------------- /releases/CR3.src.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Vibration API 5 | 6 | 7 | 31 | 32 | 33 |
34 | This specification defines an API that provides access to the vibration 35 | mechanism of the hosting device. Vibration is a form of tactile feedback. 36 |
37 | 38 |
39 |

40 | The following changes have been made 41 | since the 42 | W3C Last Call Working Draft 19 June 2014 43 | (diff): 44 |

45 | 52 |

53 | The CR exit criterion is two interoperable deployed implementations of 54 | each feature. No features are marked as 'at-risk'. The group will create 55 | an 56 | Implementation Report. 57 |

58 |

59 | This document represents the consensus of the group on the scope and 60 | features of the Vibration API. It should be noted that the group is 61 | aware of more advanced use cases that cannot be realized using this 62 | simpler first version. The intent is to address them in a future 63 | revision. 64 |

65 |
66 | 67 |
68 |

Introduction

69 |

70 | The API is specifically designed to address use cases that require 71 | simple tactile feedback only. Use cases requiring more fine-grained 72 | control are out of scope for this specification. This API is not meant 73 | to be used as a generic notification mechanism. Such use cases may be 74 | handled using the Web Notifications [[notifications]] 75 | specification. In addition, determining whether vibration is enabled 76 | is out of scope for this specification. 77 |

78 |
79 | 80 |
81 |

82 | This specification defines conformance criteria that apply to a single 83 | product: the user agent that implements the 84 | interfaces that it contains. 85 |

86 |

87 | Implementations that use ECMAScript to implement the APIs defined in 88 | this specification must implement them in a manner consistent with the 89 | ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], 90 | as this specification uses that specification and terminology. 91 |

92 |
93 | 94 |
95 |

Terminology

96 |

97 | The concepts 98 | browsing context and 99 | 100 | spin the event loop are defined in [[!HTML5]]. 101 |

102 |
103 | 104 |
105 |

Vibration Interface

106 |
107 |
boolean vibrate()
108 |
109 |
110 |
(unsigned long or sequence<unsigned long>) pattern
111 |
112 |
113 |
114 |
115 | 116 |

117 | The vibrate() 118 | method, when invoked, MUST run the algorithm 119 | for processing vibration patterns. 120 |

121 |

122 | The rules for processing vibration patterns are as given in 123 | the following algorithm: 124 |

125 |
    126 |
  1. 127 | Let pattern be the value of the first argument. 128 |
    2. 129 |
  2. 130 | If pattern is a list, proceed to the next step. 131 | Otherwise run the following substeps: 132 |
      133 |
    1. 134 | Let list be an initially empty list, and add 135 | pattern to list. 136 |
      2. 137 |
    2. 138 | Set pattern to list. 139 |
      3. 140 |
    141 |
    3. 142 |
  3. 143 | Let max length be an implementation-dependent maximum 144 | length of pattern. 145 |
    146 | If the length of a pattern is greater than max length an 147 | implementation of this API could consider breaking the request 148 | effectively into multiple shorter requests internally to achieve 149 | the same effect, rather than ignoring what follows the max length. 150 | There are cases, however, where it is appropriate to ignore the 151 | pattern exceeding the max length. An example is if the length is so 152 | long that it would effectively create a denial of service attack on 153 | the user. A web application might also make multiple requests if it 154 | is known to the application that the length is too long for some 155 | implementations and a possible gap in between patterns is 156 | acceptable. 157 |
    158 |
    4. 159 |
  4. 160 | If the length of pattern is greater than 161 | max length, truncate pattern, leaving only 162 | the first max length entries. 163 |
    164 | If the length of the pattern is even and not zero then 165 | the last entry in the pattern will have no effect so an 166 | implementation can remove it from the pattern at this point. 167 |
    168 |
    5. 169 |
  5. 170 | Let max duration be an implementation-dependent maximum 171 | duration for a single vibration entry in a pattern. 172 |
    6. 173 |
  6. 174 | For each entry in pattern whose value is greater than 175 | max duration, set the entry's value to 176 | max duration. 177 |
    7. 178 |
  7. 179 | If the 180 | 181 | hidden attribute [[!PAGE-VISIBILITY]] is set to true, 182 | then return false and terminate these steps. 183 |
    184 | A trusted (also known as privileged) application that integrates 185 | closely with the operating system's functionality may vibrate the 186 | device even if such an application is not visible at all, and thus 187 | may ignore the previous step. 188 |
    189 |
    8. 190 |
  8. 191 | An implementation MAY return false and terminate these steps. 192 |
    193 | For example, an implementation might abort the 194 | algorithm because the user has set a preference indicating that 195 | pages at a given origin should never be able to vibrate the device, 196 | or an implementation might cap the total amount of time a page may 197 | cause the device to vibrate and reject requests in excess of this 198 | limit. 199 |
    200 |
    9. 201 |
  9. 202 | If there is a pre-existing instance of the processing vibration 203 | patterns algorithm running for this browsing context, run the 204 | following substeps: 205 |
      206 |
    1. 207 | Cancel the pre-existing instance of the processing vibration 208 | patterns algorithm, if any. 209 |
      2. 210 |
    2. 211 | If pattern is an empty list, contains a single entry 212 | with a value of 0, or if the device is unable to vibrate, then 213 | return true and terminate these steps. 214 |
      3. 215 |
    216 |
  10. 217 | Return true, and then continue running these steps asynchronously. 218 |
    11. 219 |
  11. 220 | For each time in pattern, run the following 221 | substeps: 222 |
      223 |
    1. 224 | If the index of time is even (the first entry has 225 | index 0), vibrate the device for time milliseconds. 226 |
      2. 227 |
    2. 228 | Otherwise wait for time milliseconds. 229 |
      3. 230 |
    231 |
    12. 232 |
233 |

234 | When the 235 | 236 | visibilitychange event [[!PAGE-VISIBILITY]] is dispatched at 237 | the Document in a browsing context, the 238 | user agent MUST cancel the 239 | pre-existing instance of the processing vibration patterns 240 | algorithm, if any. 241 |

242 |
243 | 244 |
245 |

Examples

246 |

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

249 |         // vibrate for 1000 ms
250 |         navigator.vibrate(1000);
251 |         
252 |         // or alternatively
253 |         navigator.vibrate([1000]);
254 |
255 |

256 | In the following example the pattern will cause the device to vibrate 257 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 258 |

259 | 
260 |         navigator.vibrate([50, 100, 150]);
261 |
262 |

263 |

264 | The following example cancels any existing vibrations: 265 |

266 | 
267 |           // cancel any existing vibrations
268 |           navigator.vibrate(0);
269 |           
270 |           // or alternatively
271 |           navigator.vibrate([]);
272 |
273 |
274 |
275 |

Acknowledgements

276 |

277 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 278 | Sicking, and the Mozilla WebAPI team for their contributions, and for 279 | providing the WebVibrator prototype as an initial input. 280 |

281 |
282 | 283 | 284 | -------------------------------------------------------------------------------- /releases/LC2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Vibration API 5 | 6 | 7 | 8 | 425 |
426 |

427 | 428 | W3C 429 | 430 |

431 |

Vibration API

432 | 433 |

W3C Last Call Working Draft

434 |
435 | 436 |
This version:
437 |
http://www.w3.org/TR/2013/WD-vibration-20130523/
438 |
Latest published version:
439 |
http://www.w3.org/TR/vibration/
440 | 441 | 442 |
Latest editor's draft:
443 |
http://dev.w3.org/2009/dap/vibration/
444 | 445 | 446 | 447 | 448 | 449 |
Previous version:
450 |
http://www.w3.org/TR/2012/CR-vibration-20120508/
451 | 452 | 453 |
Editor:
454 |
Anssi Kostiainen, Intel
455 | 456 | 457 | 458 |
459 | 460 | 461 | 462 | 463 | 464 |

465 | Copyright © 466 | 2013 467 | 468 | W3C® 469 | (MIT, 470 | ERCIM, 471 | Keio, Beihang), All Rights Reserved. 472 | W3C liability, 473 | trademark and 474 | document use rules apply. 475 |

476 | 477 | 478 |
479 |
480 |

Abstract

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

Status of This Document

484 | 485 | 486 | 487 |

488 | This section describes the status of this document at the time of its publication. Other 489 | documents may supersede this document. A list of current W3C publications and the latest revision 490 | of this technical report can be found in the W3C technical reports 491 | index at http://www.w3.org/TR/. 492 |

493 | 494 |

495 | The changes made since the 496 | 08 May 2012 W3C Candidate Recommendation (diff): 497 |

498 | 509 |

510 | This document represents the consensus of the group on the scope and 511 | features of the Vibration API. It should be noted that the group is 512 | aware of more advanced use cases that cannot be realized using this 513 | simpler first version. The intent is to address them in a future 514 | revision. 515 |

516 | 517 |

518 | This document was published by the Device APIs Working Group as a Last Call Working Draft. 519 | 520 | This document is intended to become a W3C Recommendation. 521 | 522 | 523 | If you wish to make comments regarding this document, please send them to 524 | public-device-apis@w3.org 525 | (subscribe, 526 | archives). 527 | 528 | The Last Call period ends 13 June 2013. 529 | 530 | 531 | All comments are welcome. 532 | 533 | 534 |

535 | Publication as a Last Call Working Draft does not imply endorsement by the W3C Membership. 536 | This is a draft document and may be updated, replaced or obsoleted by other documents at 537 | any time. It is inappropriate to cite this document as other than work in progress. 538 |

539 | 540 | 541 |

542 | This is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the 543 | relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process. 544 |

545 | 546 |

547 | 548 | This document was produced by a group operating under the 549 | 5 February 2004 W3C Patent Policy. 550 | 551 | 552 | 553 | 554 | W3C maintains a public list of any patent disclosures 555 | 556 | made in connection with the deliverables of the group; that page also includes instructions for 557 | disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains 558 | Essential Claim(s) must disclose the 559 | information in accordance with section 560 | 6 of the W3C Patent Policy. 561 | 562 | 563 |

564 | 565 | 566 | 567 | 568 |

Table of Contents

569 | 570 | 571 | 572 |
573 |

1. Introduction

This section is non-normative.

574 |

575 | The API is specifically designed to address use cases that require 576 | simple tactile feedback only. Use cases requiring more fine-grained 577 | control are out of scope for this specification. In addition, the API 578 | is not meant to be used as a generic notification mechanism. 579 |

580 |
581 | 582 |

2. Conformance

583 |

584 | As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, 585 | and notes in this specification are non-normative. Everything else in this specification is 586 | normative. 587 |

588 |

589 | The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, 590 | and OPTIONAL in this specification are to be interpreted as described in [RFC2119]. 591 |

592 | 593 |

594 | This specification defines conformance criteria that apply to a single 595 | product: the user agent that implements the 596 | interfaces that it contains. 597 |

598 |

599 | Implementations that use ECMAScript to implement the APIs defined in 600 | this specification must implement them in a manner consistent with the 601 | ECMAScript Bindings defined in the Web IDL specification [WEBIDL], 602 | as this specification uses that specification and terminology. 603 |

604 |
605 | 606 |
607 |

3. Terminology

608 |

609 | The concepts 610 | browsing context and 611 | 612 | spin the event loop are defined in [HTML5]. 613 |

614 |
615 | 616 |
617 |

4. Vibration Interface

618 | 
partial interface Navigator {
619 |     boolean vibrate ((unsigned long or sequence<unsigned long>) pattern);
620 | };
621 | 622 |

623 | The vibrate() 624 | method, when invoked, MUST run the algorithm 625 | for processing vibration patterns. 626 |

627 |

628 | The rules for processing vibration patterns are as given in 629 | the following algorithm: 630 |

631 |
    632 |
  1. 633 | Let pattern be the value of the first argument. 634 |
    2. 635 |
  2. 636 | If pattern is a list, proceed to the next step. 637 | Otherwise run the following substeps: 638 |
      639 |
    1. 640 | Let list be an initially empty list, and add 641 | pattern to list. 642 |
      2. 643 |
    2. 644 | Set pattern to list. 645 |
      3. 646 |
    647 |
    3. 648 |
  3. 649 | If any entry of pattern exceeds an 650 | implementation-dependent limit, then return false and terminate 651 | these steps. 652 |
    4. 653 |
  4. 654 | If the length of pattern is even and is not zero, then 655 | remove the last entry in pattern. 656 |
    5. 657 |
  5. 658 | If the length of pattern exceeds an 659 | implementation-dependent limit, then return false and terminate 660 | these steps. 661 |
    6. 662 |
  6. 663 | If the 664 | 665 | hidden attribute [PAGE-VISIBILITY] is set to true, 666 | then return false and terminate these steps. 667 |
    Note
    668 | A trusted (also known as privileged) application that integrates 669 | closely with the operating system's functionality may vibrate the 670 | device even if such an application is not visible at all, and thus 671 | may ignore the previous step. 672 |
    673 |
    7. 674 |
  7. 675 | An implementation MAY return false and terminate these steps. 676 |
    Note
    677 | For example, an implementation might abort the 678 | algorithm because the user has set a preference indicating that 679 | pages at a given origin should never be able to vibrate the device, 680 | or an implementation might cap the total amount of time a page may 681 | cause the device to vibrate and reject requests in excess of this 682 | limit. 683 |
    684 |
    8. 685 |
  8. 686 | Cancel the pre-existing instance of the processing vibration 687 | patterns algorithm, if any. 688 |
    9. 689 |
  9. 690 | If pattern is an empty list, or if the device does 691 | not provide a vibration mechanism (or it is disabled), then return 692 | true and terminate these steps. 693 |
    10. 694 |
  10. 695 | Return true, and then continue running these steps asynchronously. 696 |
    11. 697 |
  11. 698 | For each time in pattern, run the following 699 | substeps: 700 |
      701 |
    1. 702 | If the index of time is even (the first entry has 703 | index 0), vibrate the device for time milliseconds. 704 |
      2. 705 |
    2. 706 | Otherwise wait for time milliseconds. 707 |
      3. 708 |
    709 |
    12. 710 |
711 |

712 | When the 713 | 714 | visibilitychange event [PAGE-VISIBILITY] is dispatched at 715 | the Document in a browsing context, the 716 | user agent MUST cancel the 717 | pre-existing instance of the processing vibration patterns 718 | algorithm, if any. 719 |

720 |
721 | 722 |
723 |

5. Examples

This section is non-normative.

724 |

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

Example 1
// vibrate for 1000 ms
727 | navigator.vibrate(1000);
728 | 
729 | // or alternatively
730 | navigator.vibrate([1000]);
731 |

732 | In the following example the pattern will cause the device to vibrate 733 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 734 |

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

737 |

738 | The following example cancels any existing vibrations: 739 |

740 |
Example 3
// cancel any existing vibrations
741 | navigator.vibrate(0);
742 | 
743 | // or alternatively
744 | navigator.vibrate([]);
745 |
746 |
747 |

A. Acknowledgements

748 |

749 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 750 | Sicking, and the Mozilla WebAPI team for their contributions, and for 751 | providing the WebVibrator prototype as an initial input. 752 |

753 |
754 | 755 | 756 |

B. References

B.1 Normative references

[HTML5]
Robin Berjon et al. HTML5. 17 December 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/ 757 |
[PAGE-VISIBILITY]
J. Mann; A. Jain. Page Visibility. 14 May 2013. W3C Recommendation. URL: http://www.w3.org/TR/2013/REC-page-visibility-20130514/ 758 |
[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 759 |
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/2012/CR-WebIDL-20120419/ 760 |
761 | -------------------------------------------------------------------------------- /releases/LC2.src.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Vibration API 5 | 6 | 7 | 29 | 30 | 31 |
32 | This specification defines an API that provides access to the vibration 33 | mechanism of the hosting device. Vibration is a form of tactile feedback. 34 |
35 | 36 |
37 |

38 | The changes made since the 39 | 08 May 2012 W3C Candidate Recommendation (diff): 40 |

41 | 52 |

53 | This document represents the consensus of the group on the scope and 54 | features of the Vibration API. It should be noted that the group is 55 | aware of more advanced use cases that cannot be realized using this 56 | simpler first version. The intent is to address them in a future 57 | revision. 58 |

59 |
60 | 61 |
62 |

Introduction

63 |

64 | The API is specifically designed to address use cases that require 65 | simple tactile feedback only. Use cases requiring more fine-grained 66 | control are out of scope for this specification. In addition, the API 67 | is not meant to be used as a generic notification mechanism. 68 |

69 |
70 | 71 |
72 |

73 | This specification defines conformance criteria that apply to a single 74 | product: the user agent that implements the 75 | interfaces that it contains. 76 |

77 |

78 | Implementations that use ECMAScript to implement the APIs defined in 79 | this specification must implement them in a manner consistent with the 80 | ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], 81 | as this specification uses that specification and terminology. 82 |

83 |
84 | 85 |
86 |

Terminology

87 |

88 | The concepts 89 | browsing context and 90 | 91 | spin the event loop are defined in [[!HTML5]]. 92 |

93 |
94 | 95 |
96 |

Vibration Interface

97 |
98 |
boolean vibrate()
99 |
100 |
101 |
(unsigned long or sequence<unsigned long>) pattern
102 |
103 |
104 |
105 |
106 | 107 |

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

111 |

112 | The rules for processing vibration patterns are as given in 113 | the following algorithm: 114 |

115 |
    116 |
  1. 117 | Let pattern be the value of the first argument. 118 |
    2. 119 |
  2. 120 | If pattern is a list, proceed to the next step. 121 | Otherwise run the following substeps: 122 |
      123 |
    1. 124 | Let list be an initially empty list, and add 125 | pattern to list. 126 |
      2. 127 |
    2. 128 | Set pattern to list. 129 |
      3. 130 |
    131 |
    3. 132 |
  3. 133 | If any entry of pattern exceeds an 134 | implementation-dependent limit, then return false and terminate 135 | these steps. 136 |
    4. 137 |
  4. 138 | If the length of pattern is even and is not zero, then 139 | remove the last entry in pattern. 140 |
    5. 141 |
  5. 142 | If the length of pattern exceeds an 143 | implementation-dependent limit, then return false and terminate 144 | these steps. 145 |
    6. 146 |
  6. 147 | If the 148 | 149 | hidden attribute [[!PAGE-VISIBILITY]] is set to true, 150 | then return false and terminate these steps. 151 |
    152 | A trusted (also known as privileged) application that integrates 153 | closely with the operating system's functionality may vibrate the 154 | device even if such an application is not visible at all, and thus 155 | may ignore the previous step. 156 |
    157 |
    7. 158 |
  7. 159 | An implementation MAY return false and terminate these steps. 160 |
    161 | For example, an implementation might abort the 162 | algorithm because the user has set a preference indicating that 163 | pages at a given origin should never be able to vibrate the device, 164 | or an implementation might cap the total amount of time a page may 165 | cause the device to vibrate and reject requests in excess of this 166 | limit. 167 |
    168 |
    8. 169 |
  8. 170 | Cancel the pre-existing instance of the processing vibration 171 | patterns algorithm, if any. 172 |
    9. 173 |
  9. 174 | If pattern is an empty list, or if the device does 175 | not provide a vibration mechanism (or it is disabled), then return 176 | true and terminate these steps. 177 |
    10. 178 |
  10. 179 | Return true, and then continue running these steps asynchronously. 180 |
    11. 181 |
  11. 182 | For each time in pattern, run the following 183 | substeps: 184 |
      185 |
    1. 186 | If the index of time is even (the first entry has 187 | index 0), vibrate the device for time milliseconds. 188 |
      2. 189 |
    2. 190 | Otherwise wait for time milliseconds. 191 |
      3. 192 |
    193 |
    12. 194 |
195 |

196 | When the 197 | 198 | visibilitychange event [[!PAGE-VISIBILITY]] is dispatched at 199 | the Document in a browsing context, the 200 | user agent MUST cancel the 201 | pre-existing instance of the processing vibration patterns 202 | algorithm, if any. 203 |

204 |
205 | 206 |
207 |

Examples

208 |

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

211 |         // vibrate for 1000 ms
212 |         navigator.vibrate(1000);
213 |         
214 |         // or alternatively
215 |         navigator.vibrate([1000]);
216 |
217 |

218 | In the following example the pattern will cause the device to vibrate 219 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 220 |

221 | 
222 |         navigator.vibrate([50, 100, 150]);
223 |
224 |

225 |

226 | The following example cancels any existing vibrations: 227 |

228 | 
229 |           // cancel any existing vibrations
230 |           navigator.vibrate(0);
231 |           
232 |           // or alternatively
233 |           navigator.vibrate([]);
234 |
235 |
236 |
237 |

Acknowledgements

238 |

239 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 240 | Sicking, and the Mozilla WebAPI team for their contributions, and for 241 | providing the WebVibrator prototype as an initial input. 242 |

243 |
244 | 245 | 246 | -------------------------------------------------------------------------------- /releases/LC3.src.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Vibration API 5 | 6 | 7 | 36 | 37 | 38 |
39 | This specification defines an API that provides access to the vibration 40 | mechanism of the hosting device. Vibration is a form of tactile feedback. 41 |
42 | 43 |
44 |

45 | The following changes have been made 46 | since the 47 | W3C Candidate Recommendation 23 July 2013: 48 |

49 | 67 |

68 | This document represents the consensus of the group on the scope and 69 | features of the Vibration API. It should be noted that the group is 70 | aware of more advanced use cases that cannot be realized using this 71 | simpler first version. The intent is to address them in a future 72 | revision. 73 |

74 |
75 | 76 |
77 |

Introduction

78 |

79 | The API is specifically designed to address use cases that require 80 | simple tactile feedback only. Use cases requiring more fine-grained 81 | control are out of scope for this specification. This API is not meant 82 | to be used as a generic notification mechanism. Such use cases may be 83 | handled using the Web Notifications [[notifications]] 84 | specification. In addition, determining whether vibration is enabled 85 | is out of scope for this specification. 86 |

87 |
88 | 89 |
90 |

91 | This specification defines conformance criteria that apply to a single 92 | product: the user agent that implements the 93 | interfaces that it contains. 94 |

95 |

96 | Implementations that use ECMAScript to implement the APIs defined in 97 | this specification must implement them in a manner consistent with the 98 | ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], 99 | as this specification uses that specification and terminology. 100 |

101 |
102 | 103 |
104 |

Terminology

105 |

106 | The concepts 107 | browsing context and 108 | 109 | spin the event loop are defined in [[!HTML5]]. 110 |

111 |
112 | 113 |
114 |

Vibration Interface

115 |
116 |
boolean vibrate()
117 |
118 |
119 |
(unsigned long or sequence<unsigned long>) pattern
120 |
121 |
122 |
123 |
124 | 125 |

126 | The vibrate() 127 | method, when invoked, MUST run the algorithm 128 | for processing vibration patterns. 129 |

130 |

131 | The rules for processing vibration patterns are as given in 132 | the following algorithm: 133 |

134 |
    135 |
  1. 136 | Let pattern be the value of the first argument. 137 |
    2. 138 |
  2. 139 | If pattern is a list, proceed to the next step. 140 | Otherwise run the following substeps: 141 |
      142 |
    1. 143 | Let list be an initially empty list, and add 144 | pattern to list. 145 |
      2. 146 |
    2. 147 | Set pattern to list. 148 |
      3. 149 |
    150 |
    3. 151 |
  3. 152 | Let max length be an implementation-dependent maximum 153 | length of pattern. 154 |
    155 | If the length of a pattern is greater than max length an 156 | implementation of this API could consider breaking the request 157 | effectively into multiple shorter requests internally to achieve 158 | the same effect, rather than ignoring what follows the max length. 159 | There are cases, however, where it is appropriate to ignore the 160 | pattern exceeding the max length. An example is if the length is so 161 | long that it would effectively create a denial of service attack on 162 | the user. A web application might also make multiple requests if it 163 | is known to the application that the length is too long for some 164 | implementations and a possible gap in between patterns is 165 | acceptable. 166 |
    167 |
    4. 168 |
  4. 169 | If the length of pattern is greater than 170 | max length, truncate pattern, leaving only 171 | the first max length entries. 172 |
    5. 173 |
  5. 174 | If the length of pattern is even and is not zero, then 175 | remove the last entry in pattern. 176 |
    6. 177 |
  6. 178 | Let max duration be an implementation-dependent maximum 179 | duration for a single vibration entry in a pattern. 180 |
    7. 181 |
  7. 182 | For each entry in pattern whose value is greater than 183 | max duration, set the entry's value to 184 | max duration. 185 |
    8. 186 |
  8. 187 | If the 188 | 189 | hidden attribute [[!PAGE-VISIBILITY]] is set to true, 190 | then return false and terminate these steps. 191 |
    192 | A trusted (also known as privileged) application that integrates 193 | closely with the operating system's functionality may vibrate the 194 | device even if such an application is not visible at all, and thus 195 | may ignore the previous step. 196 |
    197 |
    9. 198 |
  9. 199 | An implementation MAY return false and terminate these steps. 200 |
    201 | For example, an implementation might abort the 202 | algorithm because the user has set a preference indicating that 203 | pages at a given origin should never be able to vibrate the device, 204 | or an implementation might cap the total amount of time a page may 205 | cause the device to vibrate and reject requests in excess of this 206 | limit. 207 |
    208 |
    10. 209 |
  10. 210 | If there is a pre-existing instance of the processing vibration 211 | patterns algorithm running for this browsing context, run the 212 | following substeps: 213 |
      214 |
    1. 215 | Cancel the pre-existing instance of the processing vibration 216 | patterns algorithm, if any. 217 |
      2. 218 |
    2. 219 | If pattern is an empty list, or if the device is 220 | unable to vibrate, then return true and terminate these steps. 221 |
      3. 222 |
    223 |
  11. 224 | Return true, and then continue running these steps asynchronously. 225 |
    12. 226 |
  12. 227 | For each time in pattern, run the following 228 | substeps: 229 |
      230 |
    1. 231 | If the index of time is even (the first entry has 232 | index 0), vibrate the device for time milliseconds. 233 |
      2. 234 |
    2. 235 | Otherwise wait for time milliseconds. 236 |
      3. 237 |
    238 |
    13. 239 |
240 |

241 | When the 242 | 243 | visibilitychange event [[!PAGE-VISIBILITY]] is dispatched at 244 | the Document in a browsing context, the 245 | user agent MUST cancel the 246 | pre-existing instance of the processing vibration patterns 247 | algorithm, if any. 248 |

249 |
250 | 251 |
252 |

Examples

253 |

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

256 |         // vibrate for 1000 ms
257 |         navigator.vibrate(1000);
258 |         
259 |         // or alternatively
260 |         navigator.vibrate([1000]);
261 |
262 |

263 | In the following example the pattern will cause the device to vibrate 264 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 265 |

266 | 
267 |         navigator.vibrate([50, 100, 150]);
268 |
269 |

270 |

271 | The following example cancels any existing vibrations: 272 |

273 | 
274 |           // cancel any existing vibrations
275 |           navigator.vibrate(0);
276 |           
277 |           // or alternatively
278 |           navigator.vibrate([]);
279 |
280 |
281 |
282 |

Acknowledgements

283 |

284 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 285 | Sicking, and the Mozilla WebAPI team for their contributions, and for 286 | providing the WebVibrator prototype as an initial input. 287 |

288 |
289 | 290 | 291 | -------------------------------------------------------------------------------- /releases/LC4.src.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Vibration API 5 | 6 | 7 | 36 | 37 | 38 |
39 | This specification defines an API that provides access to the vibration 40 | mechanism of the hosting device. Vibration is a form of tactile feedback. 41 |
42 | 43 |
44 |

45 | The following changes have been made 46 | since the 47 | W3C Last Call Working Draft 11 February 2014 48 | (diff): 49 |

50 | 59 |

60 | This document represents the consensus of the group on the scope and 61 | features of the Vibration API. It should be noted that the group is 62 | aware of more advanced use cases that cannot be realized using this 63 | simpler first version. The intent is to address them in a future 64 | revision. 65 |

66 |
67 | 68 |
69 |

Introduction

70 |

71 | The API is specifically designed to address use cases that require 72 | simple tactile feedback only. Use cases requiring more fine-grained 73 | control are out of scope for this specification. This API is not meant 74 | to be used as a generic notification mechanism. Such use cases may be 75 | handled using the Web Notifications [[notifications]] 76 | specification. In addition, determining whether vibration is enabled 77 | is out of scope for this specification. 78 |

79 |
80 | 81 |
82 |

83 | This specification defines conformance criteria that apply to a single 84 | product: the user agent that implements the 85 | interfaces that it contains. 86 |

87 |

88 | Implementations that use ECMAScript to implement the APIs defined in 89 | this specification must implement them in a manner consistent with the 90 | ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], 91 | as this specification uses that specification and terminology. 92 |

93 |
94 | 95 |
96 |

Terminology

97 |

98 | The concepts 99 | browsing context and 100 | 101 | spin the event loop are defined in [[!HTML5]]. 102 |

103 |
104 | 105 |
106 |

Vibration Interface

107 |
108 |
boolean vibrate()
109 |
110 |
111 |
(unsigned long or sequence<unsigned long>) pattern
112 |
113 |
114 |
115 |
116 | 117 |

118 | The vibrate() 119 | method, when invoked, MUST run the algorithm 120 | for processing vibration patterns. 121 |

122 |

123 | The rules for processing vibration patterns are as given in 124 | the following algorithm: 125 |

126 |
    127 |
  1. 128 | Let pattern be the value of the first argument. 129 |
    2. 130 |
  2. 131 | If pattern is a list, proceed to the next step. 132 | Otherwise run the following substeps: 133 |
      134 |
    1. 135 | Let list be an initially empty list, and add 136 | pattern to list. 137 |
      2. 138 |
    2. 139 | Set pattern to list. 140 |
      3. 141 |
    142 |
    3. 143 |
  3. 144 | Let max length be an implementation-dependent maximum 145 | length of pattern. 146 |
    147 | If the length of a pattern is greater than max length an 148 | implementation of this API could consider breaking the request 149 | effectively into multiple shorter requests internally to achieve 150 | the same effect, rather than ignoring what follows the max length. 151 | There are cases, however, where it is appropriate to ignore the 152 | pattern exceeding the max length. An example is if the length is so 153 | long that it would effectively create a denial of service attack on 154 | the user. A web application might also make multiple requests if it 155 | is known to the application that the length is too long for some 156 | implementations and a possible gap in between patterns is 157 | acceptable. 158 |
    159 |
    4. 160 |
  4. 161 | If the length of pattern is greater than 162 | max length, truncate pattern, leaving only 163 | the first max length entries. 164 |
    165 | If the length of the pattern is even and not zero then 166 | the last entry in the pattern will have no effect so an 167 | implementation can remove it from the pattern at this point. 168 |
    169 |
    5. 170 |
  5. 171 | Let max duration be an implementation-dependent maximum 172 | duration for a single vibration entry in a pattern. 173 |
    6. 174 |
  6. 175 | For each entry in pattern whose value is greater than 176 | max duration, set the entry's value to 177 | max duration. 178 |
    7. 179 |
  7. 180 | If the 181 | 182 | hidden attribute [[!PAGE-VISIBILITY]] is set to true, 183 | then return false and terminate these steps. 184 |
    185 | A trusted (also known as privileged) application that integrates 186 | closely with the operating system's functionality may vibrate the 187 | device even if such an application is not visible at all, and thus 188 | may ignore the previous step. 189 |
    190 |
    8. 191 |
  8. 192 | An implementation MAY return false and terminate these steps. 193 |
    194 | For example, an implementation might abort the 195 | algorithm because the user has set a preference indicating that 196 | pages at a given origin should never be able to vibrate the device, 197 | or an implementation might cap the total amount of time a page may 198 | cause the device to vibrate and reject requests in excess of this 199 | limit. 200 |
    201 |
    9. 202 |
  9. 203 | If there is a pre-existing instance of the processing vibration 204 | patterns algorithm running for this browsing context, run the 205 | following substeps: 206 |
      207 |
    1. 208 | Cancel the pre-existing instance of the processing vibration 209 | patterns algorithm, if any. 210 |
      2. 211 |
    2. 212 | If pattern is an empty list, or if the device is 213 | unable to vibrate, then return true and terminate these steps. 214 |
      3. 215 |
    216 |
  10. 217 | Return true, and then continue running these steps asynchronously. 218 |
    11. 219 |
  11. 220 | For each time in pattern, run the following 221 | substeps: 222 |
      223 |
    1. 224 | If the index of time is even (the first entry has 225 | index 0), vibrate the device for time milliseconds. 226 |
      2. 227 |
    2. 228 | Otherwise wait for time milliseconds. 229 |
      3. 230 |
    231 |
    12. 232 |
233 |

234 | When the 235 | 236 | visibilitychange event [[!PAGE-VISIBILITY]] is dispatched at 237 | the Document in a browsing context, the 238 | user agent MUST cancel the 239 | pre-existing instance of the processing vibration patterns 240 | algorithm, if any. 241 |

242 |
243 | 244 |
245 |

Examples

246 |

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

249 |         // vibrate for 1000 ms
250 |         navigator.vibrate(1000);
251 |         
252 |         // or alternatively
253 |         navigator.vibrate([1000]);
254 |
255 |

256 | In the following example the pattern will cause the device to vibrate 257 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 258 |

259 | 
260 |         navigator.vibrate([50, 100, 150]);
261 |
262 |

263 |

264 | The following example cancels any existing vibrations: 265 |

266 | 
267 |           // cancel any existing vibrations
268 |           navigator.vibrate(0);
269 |           
270 |           // or alternatively
271 |           navigator.vibrate([]);
272 |
273 |
274 |
275 |

Acknowledgements

276 |

277 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 278 | Sicking, and the Mozilla WebAPI team for their contributions, and for 279 | providing the WebVibrator prototype as an initial input. 280 |

281 |
282 | 283 | 284 | -------------------------------------------------------------------------------- /releases/PER.src.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Vibration API 6 | 7 | 8 | 11 | 77 | 78 | 79 |
80 | This specification defines an API that provides access to the vibration 81 | mechanism of the hosting device. Vibration is a form of tactile feedback. 82 |
83 |
84 |

85 | The following editorial changes were made since the W3C Recommendation 87 | 10 February 2015 (diff): 88 |

89 | 102 |
103 |
104 |

105 | Introduction 106 |

107 |

108 | The API is specifically designed to address use cases that require 109 | simple tactile feedback only. Use cases requiring more fine-grained 110 | control are out of scope for this specification. This API is not meant 111 | to be used as a generic notification mechanism. Such use cases may be 112 | handled using the Notifications API [[NOTIFICATIONS]] 113 | specification. In addition, determining whether vibration is enabled is 114 | out of scope for this specification. 115 |

116 |
117 |
118 |

119 | This specification defines conformance criteria that apply to a single 120 | product: the user agent that implements the 121 | interfaces that it contains. 122 |

123 |

124 | Implementations that use ECMAScript to implement the APIs defined in 125 | this specification must implement them in a manner consistent with the 126 | ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL-1]], 127 | as this specification uses that specification and terminology. 128 |

129 |
130 |
131 |

132 | Terminology 133 |

134 |

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

141 |
142 |
143 |

144 | Vibration Interface 145 |

146 | 
147 |         typedef (unsigned long or sequence<unsigned long>) VibratePattern;
148 | 
149 |         partial interface Navigator {
150 |             boolean vibrate (VibratePattern pattern);
151 |         };
152 |
153 |

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

157 |

158 | The rules for processing vibration patterns are as given in 159 | the following algorithm: 160 |

161 |
    162 |
  1. Let pattern be the first method argument of the 163 | vibrate() method. 164 |
    2. 165 |
  2. Let valid pattern be the result of passing 166 | pattern to validate and normalize. 167 |
    3. 168 |
  3. If the result of running the steps to 170 | determine the visibility state [[!PAGE-VISIBILITY-2]] is not 171 | visible, then return false and terminate these steps. 172 |
    173 | A trusted (also known as privileged) application that integrates 174 | closely with the operating system's functionality may vibrate the 175 | device even if such an application is not visible at all, and thus 176 | may ignore the previous step. 177 |
    178 |
    4. 179 |
  4. 180 | Perform vibration with valid pattern. 181 |
    5. 182 |
183 |

184 | To validate and normalize a vibration pattern given 185 | pattern, run these steps: 186 |

187 |
    188 |
  1. If pattern is a list, proceed to the next step. 189 | Otherwise run the following substeps: 190 |
      191 |
    1. Let list be an initially empty list, and add 192 | pattern to list. 193 |
      2. 194 |
    2. Set pattern to list. 195 |
      3. 196 |
    197 |
    2. 198 |
  2. Let max length be an implementation-dependent maximum 199 | length of pattern. 200 |
    201 | If the length of a pattern is greater than max length an 202 | implementation of this API could consider breaking the request 203 | effectively into multiple shorter requests internally to achieve 204 | the same effect, rather than ignoring what follows the max length. 205 | There are cases, however, where it is appropriate to ignore the 206 | pattern exceeding the max length. An example is if the length is so 207 | long that it would effectively create a denial of service attack on 208 | the user. A web application might also make multiple requests if it 209 | is known to the application that the length is too long for some 210 | implementations and a possible gap in between patterns is 211 | acceptable. 212 |
    213 |
    3. 214 |
  3. If the length of pattern is greater than max 215 | length, truncate pattern, leaving only the first 216 | max length entries. 217 |
    218 | If the length of the pattern is even and not zero then 219 | the last entry in the pattern will have no effect so an 220 | implementation can remove it from the pattern at this 221 | point. 222 |
    223 |
    4. 224 |
  4. Let max duration be an implementation-dependent maximum 225 | duration for a single vibration entry in a pattern. 226 |
    5. 227 |
  5. For each entry in pattern whose value is greater than 228 | max duration, set the entry's value to max 229 | duration. 230 |
    6. 231 |
  6. Return pattern. 232 |
    7. 233 |
234 |

235 | To perform vibration using pattern, run these 236 | steps: 237 |

238 |
    239 |
  1. An implementation MAY return false and terminate these steps. 240 |
    241 | For example, an implementation might abort the algorithm because no 242 | vibration hardware is present, the user has set a preference 243 | indicating that pages at a given origin should never be able to 244 | vibrate the device, or an implementation might cap the total amount 245 | of time a page may cause the device to vibrate and reject requests 246 | in excess of this limit. 247 |
    248 |
    2. 249 |
  2. If another instance of the perform vibration algorithm is 250 | already running, run the following substeps: 251 |
      252 |
    1. Abort that other instance of the perform vibration 253 | algorithm, if any. 254 |
      2. 255 |
    2. If pattern is an empty list, contains a single entry 256 | with a value of 0, or if the device is unable to vibrate, then 257 | return true and terminate these steps. 258 |
      3. 259 |
    260 |
    3. 261 |
  3. Return true, and then continue running these steps asynchronously. 262 |
    4. 263 |
  4. For each time in pattern, run the following 264 | substeps: 265 |
      266 |
    1. If the index of time is even (the first entry has 267 | index 0), vibrate the device for time milliseconds. 268 |
      2. 269 |
    2. Otherwise wait for time milliseconds. 270 |
      3. 271 |
    272 |
    5. 273 |
274 |

275 | When the user agent determines that the visibility 277 | state of the Document of the top-level browsing 278 | context changes, it MUST abort the already running processing 279 | vibration patterns algorithm, if any. 280 |

281 |
282 |
283 |

284 | Security and privacy considerations 285 |

286 |

287 | Vibration API is not a source of data on its own and as such is not 288 | producing any data possible to consume on the Web. However, it is known 289 | that it can serve as a source of events for other APIs. In particular, 290 | it is known that certain sensors such as accelerometers or gyroscopes 291 | are prone to tiny imperfections during their manufacturing. As such, 292 | they provide a fingerprinting surface that can be exploited utilizing 293 | the vibration stimuli generated via the Vibration API. In this sense, 294 | Vibration API provides an indirect privacy risk, in conjunction with 295 | other mechanisms. This can create possibly unexpected privacy risks, 296 | including cross-device tracking and communication. Additionally, a 297 | device that is vibrating might be visible to external observers and 298 | enable physical identification, and possibly tracking of the user. 299 |

300 |

301 | For these reasons, the user agent SHOULD inform the user when the API 302 | is being used and provide a mechanism to disable the API (effectively 303 | no-op), on a per-origin basis or globally. 304 |

305 |
306 |
307 |

308 | Examples 309 |

310 |

311 | In the following example the device will vibrate for 1000 milliseconds 312 | (ms): 313 |

314 | 
315 |         // vibrate for 1000 ms
316 |         navigator.vibrate(1000);
317 |         
318 |         // or alternatively
319 |         navigator.vibrate([1000]);
320 |
321 |

322 | In the following example the pattern will cause the device to vibrate 323 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 324 |

325 | 
326 |         navigator.vibrate([50, 100, 150]);
327 |
328 |

329 | The following example cancels any existing vibrations: 330 |

331 | 
332 |           // cancel any existing vibrations
333 |           navigator.vibrate(0);
334 |           
335 |           // or alternatively
336 |           navigator.vibrate([]);
337 |
338 |
339 |
340 |

341 | Acknowledgements 342 |

343 |

344 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 345 | Sicking, and the Mozilla WebAPI team for their contributions, and for 346 | providing the WebVibrator prototype as an initial input. Thanks to Anne 347 | van Kesteren for suggestions on how to make the specification reusable 348 | in other contexts, and to Lukasz Olejnik for the privacy 349 | considerations. Finally, thanks to Zhiqiang Zhang for the Simplified 350 | Chinese translation. 351 |

352 |
353 | 354 | 355 | -------------------------------------------------------------------------------- /releases/PR.src.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Vibration API 5 | 6 | 7 | 41 | 42 | 43 |
44 | This specification defines an API that provides access to the vibration 45 | mechanism of the hosting device. Vibration is a form of tactile feedback. 46 |
47 | 48 |
49 |

50 | The following editorial changes were made since the 51 | 52 | W3C Candidate Recommendation 09 September 2014 53 | (diff): 54 |

55 | 67 |

68 | This document represents the consensus of the group on the scope and 69 | features of the Vibration API. It should be noted that the group is 70 | aware of more advanced use cases that cannot be realized using this 71 | simpler first version. The intent is to address them in a future 72 | revision. 73 |

74 |
75 | 76 |
77 |

Introduction

78 |

79 | The API is specifically designed to address use cases that require 80 | simple tactile feedback only. Use cases requiring more fine-grained 81 | control are out of scope for this specification. This API is not meant 82 | to be used as a generic notification mechanism. Such use cases may be 83 | handled using the Notifications API [[NOTIFICATIONS]] 84 | specification. In addition, determining whether vibration is enabled 85 | is out of scope for this specification. 86 |

87 |
88 | 89 |
90 |

91 | This specification defines conformance criteria that apply to a single 92 | product: the user agent that implements the 93 | interfaces that it contains. 94 |

95 |

96 | Implementations that use ECMAScript to implement the APIs defined in 97 | this specification must implement them in a manner consistent with the 98 | ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], 99 | as this specification uses that specification and terminology. 100 |

101 |
102 | 103 |
104 |

Terminology

105 |

106 | The concepts 107 | browsing context and 108 | 109 | spin the event loop are defined in [[!HTML5]]. 110 |

111 |
112 | 113 |
114 |

Vibration Interface

115 |
116 |
117 |
boolean vibrate()
118 |
119 |
120 |
VibratePattern pattern
121 |
122 |
123 |
124 |
125 | 126 |

127 | The vibrate() 128 | method, when invoked, MUST run the algorithm 129 | for processing vibration patterns. 130 |

131 |

132 | The rules for processing vibration patterns are as given in 133 | the following algorithm: 134 |

135 |
    136 |
  1. 137 | Let pattern be the first method argument of the 138 | vibrate() method. 139 |
    2. 140 |
  2. 141 | Let valid pattern be the result of passing 142 | pattern to validate and normalize. 143 |
    3. 144 |
  3. 145 | If the 146 | 147 | hidden attribute [[!PAGE-VISIBILITY]] is set to true, 148 | then return false and terminate these steps. 149 |
    150 | A trusted (also known as privileged) application that integrates 151 | closely with the operating system's functionality may vibrate the 152 | device even if such an application is not visible at all, and thus 153 | may ignore the previous step. 154 |
    155 |
    4. 156 |
  4. 157 | Perform vibration with valid pattern. 158 |
    5. 159 |
160 |

161 | To validate and normalize a vibration pattern given 162 | pattern, run these steps: 163 |

164 |
    165 |
  1. 166 | If pattern is a list, proceed to the next step. 167 | Otherwise run the following substeps: 168 |
      169 |
    1. 170 | Let list be an initially empty list, and add 171 | pattern to list. 172 |
      2. 173 |
    2. 174 | Set pattern to list. 175 |
      3. 176 |
    177 |
    2. 178 |
  2. 179 | Let max length be an implementation-dependent maximum 180 | length of pattern. 181 |
    182 | If the length of a pattern is greater than max length an 183 | implementation of this API could consider breaking the request 184 | effectively into multiple shorter requests internally to achieve 185 | the same effect, rather than ignoring what follows the max length. 186 | There are cases, however, where it is appropriate to ignore the 187 | pattern exceeding the max length. An example is if the length is so 188 | long that it would effectively create a denial of service attack on 189 | the user. A web application might also make multiple requests if it 190 | is known to the application that the length is too long for some 191 | implementations and a possible gap in between patterns is 192 | acceptable. 193 |
    194 |
    3. 195 |
  3. 196 | If the length of pattern is greater than 197 | max length, truncate pattern, leaving only 198 | the first max length entries. 199 |
    200 | If the length of the pattern is even and not zero then 201 | the last entry in the pattern will have no effect so an 202 | implementation can remove it from the pattern at this point. 203 |
    204 |
    4. 205 |
  4. 206 | Let max duration be an implementation-dependent maximum 207 | duration for a single vibration entry in a pattern. 208 |
    5. 209 |
  5. 210 | For each entry in pattern whose value is greater than 211 | max duration, set the entry's value to 212 | max duration. 213 |
    6. 214 |
  6. 215 | Return pattern. 216 |
    7. 217 |
218 |

219 | To perform vibration using pattern, run these 220 | steps: 221 |

222 |
    223 |
  1. 224 | An implementation MAY return false and terminate these steps. 225 |
    226 | For example, an implementation might abort the 227 | algorithm because the user has set a preference indicating that 228 | pages at a given origin should never be able to vibrate the device, 229 | or an implementation might cap the total amount of time a page may 230 | cause the device to vibrate and reject requests in excess of this 231 | limit. 232 |
    233 |
    2. 234 |
  2. 235 | If another instance of the perform vibration algorithm is 236 | already running, run the following substeps: 237 |
      238 |
    1. 239 | Abort that other instance of the perform vibration 240 | algorithm, if any. 241 |
      2. 242 |
    2. 243 | If pattern is an empty list, contains a single entry 244 | with a value of 0, or if the device is unable to vibrate, then 245 | return true and terminate these steps. 246 |
      3. 247 |
    248 |
  3. 249 | Return true, and then continue running these steps asynchronously. 250 |
    4. 251 |
  4. 252 | For each time in pattern, run the following 253 | substeps: 254 |
      255 |
    1. 256 | If the index of time is even (the first entry has 257 | index 0), vibrate the device for time milliseconds. 258 |
      2. 259 |
    2. 260 | Otherwise wait for time milliseconds. 261 |
      3. 262 |
    263 |
    5. 264 |
265 |

266 | When the 267 | 268 | visibilitychange event [[!PAGE-VISIBILITY]] is dispatched at 269 | the Document in a browsing context, the 270 | user agent MUST abort the 271 | already running processing vibration patterns algorithm, if any. 272 |

273 |
274 | 275 |
276 |

Examples

277 |

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

280 |         // vibrate for 1000 ms
281 |         navigator.vibrate(1000);
282 |         
283 |         // or alternatively
284 |         navigator.vibrate([1000]);
285 |
286 |

287 | In the following example the pattern will cause the device to vibrate 288 | for 50 ms, be still for 100 ms, and then vibrate for 150 ms: 289 |

290 | 
291 |         navigator.vibrate([50, 100, 150]);
292 |
293 |

294 |

295 | The following example cancels any existing vibrations: 296 |

297 | 
298 |           // cancel any existing vibrations
299 |           navigator.vibrate(0);
300 |           
301 |           // or alternatively
302 |           navigator.vibrate([]);
303 |
304 |
305 |
306 |

Acknowledgements

307 |

308 | The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas 309 | Sicking, and the Mozilla WebAPI team for their contributions, and for 310 | providing the WebVibrator prototype as an initial input. Thanks to 311 | Anne van Kesteren for suggestions on how to make the specification 312 | reusable in other contexts. 313 |

314 |
315 | 316 | 317 | -------------------------------------------------------------------------------- /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": 43696 3 | , "contacts": "himorin" 4 | , "repo-type": "rec-track" 5 | } 6 | --------------------------------------------------------------------------------