Web Push userVisibleOnly Details

[aluhrs13]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/PushSubscriptionOptions/userVisibleOnly

What specific section or headline is this issue about?

No response

What information was incorrect, unhelpful, or incomplete?

The Push API spec includes a userVisibleOnly option, that MDN implies is fully functional for WebKit or Chromium browsers but isn't actually the case. Both will reject the promise requiring it to be true.

Normally an API predictably rejecting a promise isn't a huge deal, but if a developer goes through the overhead of understanding applicationServerKey, VAPID, push services, etc. only to see "Promise Rejected", that could be extremely frustrating.

At a minimum it seems like the page PushSubscription options should include details on this, but the following pages could probably use more aggressive dissuading developers from trying to use push for non-visible cases:

1. https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe#syntax
2. https://developer.mozilla.org/en-US/docs/Web/API/Push_API
3. https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Tutorials/js13kGames/Re-engageable_Notifications_Push

For completeness, I could I only find one page online calling out this behavior - https://web.dev/articles/push-notifications-subscribing-a-user#uservisibleonly_options

What did you expect to see?

That browsers might reject a subscription if userVisibleOnly is set to false. Happy to open an issue and/or PR on the browser-compat-data side if that's the best place to approach this too.

Do you have any supporting links, references, or citations?

• Chromium source: https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/push_messaging/push_messaging_service_impl.cc;l=561
• WebKit source: https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/push-api/PushManager.cpp#L80

Do you have anything more you want to share?

No response

[caugner]

The read-only userVisibleOnly property on the PushSubscriptionOptions object seems to be supported in Chrome 54+, Edge 17+, Opera 41+ and partially supported in Safari 16+, according to BCD.

You're saying that browsers reject a subscription if userVisibleOnly is set to false, but this page seems to be about being able to read this property.

It looks like the userVisibleOnly property can only be set on the PushSubscriptionOptionsInit dictionary, which isn't explicitly documented on MDN, but covered by the PushManager.subscribe() article.

I agree that the definition of userVisibleOnly on that page could mention that the value must be set to true in practice, even though the specification doesn't mention this requirement.

[aluhrs13]

@caugner Yep, my bad on the wrong page, mixed up the pages when I had so many open, PushManager.subscribe() is the most correct.

[Ryuno-Ki]

I learned about this issue on Mastodon because @captainbrosset tooted about it.

When trying the demo at https://attractive-tranquil-nephew.glitch.me/ I cannot reproduce the behaviour in Firefox 115.0.2 on Debian/Linux. Nevertheless I would be willing to submit a PR that addresses this:

It looks like the userVisibleOnly property can only be set on the PushSubscriptionOptionsInit dictionary, which isn't explicitly documented on MDN, but covered by the PushManager.subscribe() article.

I agree that the definition of userVisibleOnly on that page could mention that the value must be set to true in practice, even though the specification doesn't mention this requirement.

[captainbrosset]

The error message seems to be displayed on Chromium-based browsers (in the Console panel of DevTools). Nothing seems to happen in Firefox.

[Ryuno-Ki]

Confirmed (as in: Promise rejected logged to the console) with Chromium Version 119.0.6045.159 (Official Build) built on Debian 12.2, running on Debian (64-bit).

[Ryuno-Ki]

I've submitted #30369 and checked the other MDN pages. As far as I can tell, the property is always set to true there.

[Josh-Cena]

I think this is sufficiently fixed by #30369