Misc non-privacy concerns with the API

[pes10k]

This issue is filed as part of the PING review requested here w3cping/privacy-request#138

The following are a list of non-privacy related concerns that were identified during the PING review.

• the API describes async behavior (the vibration happens at some point after the vibrate() all, but uses a sync API. I suggest making this an async API instead
• the text seems contradictory. For example, in the "Validate and Normalize" subsection, the first note says implementors could respond to a too-long vibration request in a bunch of different ways (reject it, truncate it, split it into multiple vibrations). However item 2 in that subsection says that implementors must truncate. This is confusing
• the large amount of intentionally un-standardized behavior is concerning in general (e.g., what to do with a too-long vibrate request, whether a given request should trigger a vibration at all, if there is a cap on vibrations, what makes a page trusted and so can vibrate even if the page isn't visible, and even ultimately when vibrate() returns true or false)

[anssiko]

Thanks @pes10k for this non-privacy feedback! We appreciate your group taking your time to provide feedback also outside your immediate privacy scope. Please see the answers below. Perhaps unsurprisingly, historical reasons and web compatibility play a key role here too on how the API has evolved.

the API describes async behavior (the vibration happens at some point after the vibrate() all, but uses a sync API. I suggest making this an async API instead

Making this API async at this stage may not be possible without breaking existing content. The initial implementation predated modern async constructs. An additional async variant might do it, but it'd coexists with the sync, probably not addressing your concern.

the text seems contradictory. For example, in the "Validate and Normalize" subsection, the first note says implementors could respond to a too-long vibration request in a bunch of different ways (reject it, truncate it, split it into multiple vibrations). However item 2 in that subsection says that implementors must truncate. This is confusing

The specification has multiple informative notes inline in its algorithms to add more color to the corresponding more concise normative text. In case of unclarity, normative text prevails.

The important normative escape hatch is the following line in the perform vibration algorithm:

An implementation MAY return false and terminate these steps.

An implementation can bail out at that step for any reason, including, but not limited to those reasons listed in the notes. This liberal bail out without being specific on the reason was to improve privacy, to not disclose information about the underlying platform, as discussed in #36 A tradeoff between privacy and functionality.

the large amount of intentionally un-standardized behavior is concerning in general (e.g., what to do with a too-long vibrate request, whether a given request should trigger a vibration at all, if there is a cap on vibrations, what makes a page trusted and so can vibrate even if the page isn't visible, and even ultimately when vibrate() returns true or false)

To address your feedback on "what makes a page trusted", I'd suggest we update the "trusted (also known as privileged) application" reference to "installed web application". This contemporary concept also ties into the Permissions API implicit signals for future-proofing. Is that a reasonable improvement?

[anssiko]

@pes10k thanks for this non-privacy feedback. We'll do a pass that our guidance is consistent and consider this issue as non-blocking for the privacy review (as is reflected in labels).