Proposal for a <geolocation> element

[andypaicu]

The goal is to define a <geolocation> element instead of the generic <permission> element, specifically to facilitate use cases that currently use the Geolocation API.

My guiding principles based on discussions with various parties:

1. Replacing the JS API call will likely be useful in some scenarios, but oftentimes developers need to have more precise control. This means that while the permission elements should allow sites to seamlessly integrate without needing to call the JS APIs, they should also have the flexibility to allow for independent API calls.
2. Usage of the capability cannot always be gated by further interaction with the permission element, there are too many cases where this does not work. But there are still sufficient use cases where it does work e.g. a “get my location” button in an address form or a bank branch locator. Both types of use cases are worth supporting.

Proposal sketch:

• The <geolocation> element inherits from the <permission> element, including all restrictions, checks, events and attributes. The <permission> element is no longer directly usable (though first we'll also need a similar <usermedia> element for camera/microphone).
  * Constraints mirroring the getCurrentPosition options field can be set via https://github.com/WICG/PEPC/blob/main/explainer.md#constraints. Importantly the preciselocation attribute can be removed from the explainer and instead its current functionality is replicated by whether the enableHighAccuracy constraint is present or not. Another approach could be to simply define attributes matching the relatively simple structure of the options dictionary. Or perhaps, to make it more generic, we can define a mechanism that automatically maps attributes with constraints provided that the constraints have a simple structure/type.
• location locationposition attribute on the element is populated with a GeolocationPosition position when said position is available (name changed so it does not clash with the location event from below)
• locationerror attribute on the element is populated with a GeolocationPositionError error if an error has occurred while trying to retrieve the location
• onlocationready onlocation event handler (associated with a newlocation event) is raised when the user has approved the site to get location and the location call has been resolved internally. The site should look at the locationposition or locationerror attributes to see whether there was a successful location retrieval or there was some error.
  * By default the element will be treated as a “one-time” location retrieval element, the user clicks on it and it retrieves the position and raises the onlocationready event. On subsequent visits, the user still has to click on it first, though probably less friction is needed (a single click rather than also a confirmation dialog) - ultimately the exact details about the friction on subsequent interactions are an user-agent implementation detail. The permission status stays unmodified during the entire process.
  * A persistent attribute can be used on the element to more closely match the behavior of the <permission> element today: it will result in a permission prompt and potentially alter the permission status.
  * The user agent should take great consideration to distinguish between persistent and not-persistent elements in such a way where there is a clear advantage for users (and sites) when the non-persistent variation is used. Otherwise we might end up with only the persistent version being used.
• (optional) A watch attribute which would alter the behavior of the element to match the watchPosition API rather than the getCurrentPosition API. Effectively this means that onlocationready is raised every time the position changes, instead of just once.
• Make the element submittable via form: alter the form serialization algorithm.
  • Adjust https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#constructing-the-form-data-set to handle parsing a <geolocation> element
  • Make the <geolocation> element a submittable element https://html.spec.whatwg.org/multipage/forms.html#category-submit
  • The <geolocation> element will submit some sensible serialization of its locationposition attribute
• The exact details of the scope of the grant after the user interacts with the permission prompt are left to the user agent (to decide which options to put in front of the user), and the user themselves (to pick out of the presented options). Broadly speaking there are 5 possible choices that user agents could consider putting in front of users when presenting a <geolocation> element-initiated permission prompt:
  • A one-shot grant which does not include separate API usage. Next interaction on the element triggers a prompt. (Added for completeness, though it does not appear that any user agent is considering this option)
  • A one-shot grant which does not include separate API usage. Next interaction on the element does not trigger a prompt (one-click location share). (Added for completeness, though it does not appear that any user agent is considering this option)
  • A one-time grant which also includes separate API usage for its duration. Next interaction on the element triggers a prompt.
  • A one-time grant which also includes separate API usage for its duration. Next interaction on the element does not trigger a prompt.
  • A permanent grant which also includes separate API usage for its duration (presumably until the permission is manually revoked).
• Ultimately it's up to the user agent which of these choices to put in front of the user. However if the site could hint that they actually make use of permanent grants, it would allow the user agent to better tailor the options they present to users based on this hint. Whether and how much of this should be spec'ed and the exact details are currently under discussion, Chrome's proposal is that an attribute be added which, when present, indicates that the site's use case benefits from the permission being granted in a permanent (not one-time) manner (this only means that the user agent presents this choice, not that the user is forced to pick this option). This would be used by sites which have user journeys that involve using the geolocation API without starting with the user interaction with the <geolocation> element.

[martinthomson]

This is great. Almost exactly what I had in mind. Thanks @andypaicu.

A few suggestions:

• onlocation is probably better than onlocationready.
• I would try to avoid use of constraints for this if possible. There are just three items in the current PositionOptions dictionary:
  • enableHighAccuracy can be its own attribute (precise?)
  • timeout can be dropped (there were good reasons for having this at the time it was defined, but I don't think those hold)
  • maximumAge can also be dropped (ditto)
• Exposing precision/uncertainty as a value is a challenge. I agree with your suggestion about only having it when high accuracy is requested, but I don't know how it would be encoded in form submissions. It's fine to always have it on a DOM-exposed attribute, either way.
• The persistent attribute seems like a good idea. (Though spelling is hard, see below.) When true, I would expect each browser to have their own UX, but I can imagine adding a button that basically amounts to "let this site follow my location when it is in the foreground". But that would not be a good default. The interaction with watch is interesting though. These are logically separate, but it is really tempting to try to link them. Given that (I think) a site with persistent permission should be able to re-trigger the form element to obtain updated location, maybe this is a case where persistence is a UX question and watching is the only thing that comes with an attribute.
• I especially like form integration for this, but I don't know how that would be spelled. Do we supply lat/long as separate fields? How would that even work? Does this need a name attribute? Or two? Or three (for precision)? This might be a case where we can have default values for names (that's weird, but <geolocation latitudename=latitude longitudename=longitude precisionname=precision> is awfully verbose).

[andypaicu]

Thank you for the feedback.

onlocation event name and using just an attribute instead of constraints seems good to me.

I'm not sure about exposing precision, so I think you read something into what I wrote that I did not think about, since you are far more familiar with this. Is it different from the accuracy field https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates/accuracy? If it's that field, it should be part of the location attribute which is a GeolocationPosition object.

For form submission I think maybe we serialize the entire GeolocationPosition object instead of sending separate fields so you would still have 1 name.

I worry about making persistent a UX option given that users already have a different kind of persistence to think about in the permission prompt (temporary vs permanent decision). Instead I would rather the site choose whether they need the persistent variant or not, and the user agent can design the UX with less friction for the non-persistent option meaning that in general sites won't pick persistent unless their use case really demands it. When it comes to watch perhaps we can disallow the combination with persistent (or perhaps we can just not support watch, since it's the far less used geolocation API).

[martinthomson]

re: precision vs. accuracy - that's right, the names on those are bad, but that's what we have (the term of art is uncertainty, but I was not able to affect that change in 2008, so we have accuracy in metres and "high accuracy", which is nonsense).

re: persistence, I think that it is the domain of the browser UX (not the spec) to determine whether something is persistent. The site can provide cues or hints, but that's all. If the goal is to enable real-time tracking (like with watchPosition), it's true that this is distinct from not prompting when returning to site on another day. However, the only one that really needs active engagement is the one where the site wants real-time updates. That's why I suggested that that get the different approach. If we can avoid supporting it explicitly, that might be OK (it's not like watchPosition is going away).

[andypaicu]

I think I can get behind that: depending on the decision made on the permission UX the permission status might or might not change. And subsequent interactions with the geolocation element might have reduced friction if the user had already previously allowed location. I do think it's important for the value of the permission element to be able to enter a state where the site cannot access your location until you've clicked the permission element, but clicking the permission element does not require a confirmation dialog afterwards. (a "pseudo-granted-if-via-geolocation-element").

My concern though is that practically speaking from the browser perspective I only really see 2 ways of doing this:

1. Keep the existing UI, but conflate some of the existing options to also have implications for the permission element (e.g. a temporary grant via the permission element will also mean that subsequent interactions with the element do not require a confirmation UI)
2. Add some extra option in the UI

Personally I don't think I'm stoked about either option (from the Chrome side at least), so that's why I think that the persistent attribute also allows the browser to decide which UI options to put in front of the user depending on how the sites wants to use geolocation in the first place. Maybe we can discuss this in a meeting.

[jan-ivar]

If I understand correctly, then persistent = not "one-timeshot". To avoid confusion, I'll comment on "one-shot":

By default the element will be treated as a [Edit: “one-shot”] location retrieval element, ... On subsequent visits... a single click rather than also a confirmation dialog ... The permission status stays unmodified during the entire process.

If we look at geolocation baseline today, then all browsers grant temporary permission (although some have bugs surfacing it in query) — So it's not clear to me what mandating that status be "unmodified" buys us. Also, "confirmation dialog" sounds like a (permission) prompt.

If we remove those differences then the website would simply be choosing browser UX, which sounds undesirable.

... ultimately the exact details about the friction on subsequent interactions are an user-agent implementation detail.

I think this is the answer.

I think I can get behind that: depending on the decision made on the permission UX the permission status might or might not change. And subsequent interactions with the geolocation element might have reduced friction if the user had already previously allowed location. ... (a "pseudo-granted-if-via-geolocation-element").

My concern though is that practically speaking from the browser perspective I only really see 2 ways of doing this

Disclaimer: we're discussing UX now, which isn't standardized :-)

It's PEPC that allows us to explore this option, so I'm glad we're nailing down its common framework, but UX is course up to individual browsers to explore.

That said, one idea I was exploring for Firefox:

[jan-ivar]

I'm just realizing "one-time" can also refer to permission, so let me edit my response above and call it "one-shot"...

[andypaicu]

What if the persistent attribute would just be a hint that browsers can use (or not) when choosing the UX to be presented to the user and there would otherwise be no mandated behavior based on its presence or absence?

[andypaicu]

If I understand correctly, then persistent = not "one-timeshot". To avoid confusion, I'll comment on "one-shot":

By default the element will be treated as a [Edit: “one-shot”] location retrieval element, ... On subsequent visits... a single click rather than also a confirmation dialog ... The permission status stays unmodified during the entire process.

If we look at geolocation baseline today, then all browsers grant temporary permission (although some have bugs surfacing it in query) — So it's not clear to me what mandating that status be "unmodified" buys us. Also, "confirmation dialog" sounds like a (permission) prompt.

If we remove those differences then the website would simply be choosing browser UX, which sounds undesirable.

Perhaps if this was a hint to the browser it would work better? I see it as a way for sites to request less than what they currently request today, if their use case allows for it.

... ultimately the exact details about the friction on subsequent interactions are an user-agent implementation detail.

I think this is the answer.

I think I can get behind that: depending on the decision made on the permission UX the permission status might or might not change. And subsequent interactions with the geolocation element might have reduced friction if the user had already previously allowed location. ... (a "pseudo-granted-if-via-geolocation-element").
My concern though is that practically speaking from the browser perspective I only really see 2 ways of doing this

Disclaimer: we're discussing UX now, which isn't standardized :-)

Yes, I know, but if browsers don't consider the entire UX (including the non-standardized aspects) when considering a feature proposal, they risk missing aspects which might end up being relevant to the platform level.

It's PEPC that allows us to explore this option, so I'm glad we're nailing down its common framework, but UX is course up to individual browsers to explore.

That said, one idea I was exploring for Firefox:

I notice that there is no way on this dialog to say "allow once" (as in "give my location this time, but the next time I push this button I want to see this dialog again"). I think as a user I would like to see that option (but adding it as an extra option seems too much like decision overload). That's an illustration of why I think persistent as an attribute would be useful, it would allow the browser to decide which options to put in front of the user. For example:

• persistent: allow always (including JS API calls), allow once, deny (including JS API calls)
• non-persistent: allow on button push, allow once, deny

[jan-ivar]

I notice that there is no way on this dialog to say "allow once" (as in "give my location this time, but the next time I push this button I want to see this dialog again"). I think as a user I would like to see that option (but adding it as an extra option seems too much like decision overload).

Right, but you're conceding it's a user option to the same request, not the website asking for "less". Which of these options to implement seems for user agents to consider, not websites.

I agree we need to look at both API and UX. But this single API design needs to serve multiple (even future) UXes.

To abstract this correctly, I think any attribute needs to be in the domain of geolocation, not permission. I think watch satisfies this because it's specific to being notified of the user's motion. But (non/)persistent as described does not (the two examples to me could describe two different browser implementations of the same API).

BTW, I also disagree users want to see the dialog again in the same document, because this doesn't exist today, and nobody's asked for it. People already expect one-time ("Allow this time") to grant for the lifetime of the page¹ in all browsers, not to the one-shot request. Ages ago, Firefox used to prompt for camera/mic each time getUserMedia() was called, and everyone unequivocally hated it.

---

_{1. saying "page" here is conservative and over-simplified. Both Chrome and Firefox extend temporary permissions across same-origin navigation till tab-close.}

[jan-ivar]

To clarify, in my mind, this is option 2 in mozilla/standards-positions#1245 (comment) transposed to geolocation:

1. persistent permission to PEPC & gCP ("zero-click")
2. persistent permission to PEPC only (but PEPC interaction grants temporary gCP permission) ("one-click")
3. one-time permission ("one-or-two-click")

IOW, the problem is scoped to where prompts appear today (on revisits, not within the same document).

I'll concede that option 3 has an advantage over 2 for users who wish to avoid making any permanent decision. Option 2 may also solidify the styling restrictions, which I know @martinthomson wanted to explore relaxing.

[jan-ivar]

That's an illustration of why I think persistent as an attribute would be useful, it would allow the browser to decide which options to put in front of the user. For example:

• persistent: allow always (including JS API calls), allow once, deny (including JS API calls)
• non-persistent: allow on button push, allow once, deny

Giving websites control over what the top choice is means it might vary from site to site, defeating muscle memory and cause some users to choose the wrong option sometimes.

Using visuals from this mockup (which I understand is not final in any way), <geolocation></geolocation> gives me (A):

...whereas <geolocation persistent></geolocation> gives me (B):

The above feels like websites influencing user choice. But also: easily solved by reordering the options as follows (C):

Some follow-up UX questions:

1. Once I've pressed "Allow only via my explicit action" in A, do I still get prompted in B?
2. Same question reversing B and A
3. Once I've pressed "Allow only via my explicit action", how do I change my mind to "Allow whenever I'm visiting this site"?

I think the answer to 3 is this will only come up if the website in a future visit ever calls navigator.geolocation.getCurrentPosition() ahead of the user pressing PEPC <geolocation></geolocation>, in which case they'll be prompted (the old fashioned way?) and get the option to "Allow always" at that point — which makes me wonder: does PEPC even need to solve "Allow always"?

[mikewest]

which I understand is not final in any way

For clarity, not only is it not final, it's barely even proposed. Consider it my personal take, with the understanding that I'm both a bad engineer and designer. I'm confident that whatever we'd end up shipping would be substantially different.

But also: easily solved by reordering the options as follows (C)

Sure. The ordering wasn't considered, it was just the simplest way to demonstrate a potential impact of the persistent[sic] attribute. I've now flipped it around in mikewest/scratchpad@1c30c65.

Some follow-up UX questions:

1. Once I've pressed "Allow only via my explicit action" in A, do I still get prompted in B?

I think we'd want to prompt in that case, yes, as the developer is asking for access to the capability across visits and without specific user interaction. We probably can't provide that without asking the user, and it seems reasonable to give the user an opportunity to make that decision.

This answer, though, probably requires us to change the visual cue of the button in some way so that users won't be surprised by a prompt. The mock does this by changing the string, but there are likely other, better options.

2. Same question reversing B and A

If the site has access to the capability without high-signal user interaction, it doesn't seem useful to prompt users when they do provide such a signal. So, I'd say that a prompt in this case is unnecessary.

3. Once I've pressed "Allow only via my explicit action", how do I change my mind to "Allow whenever I'm visiting this site"?

A good question which we need to work out. It would be ideal for there to be some affordance to make this change, and I think the right answer can range wildly between "Something in browser UI (Chrome's page info bubble, for instance)" to "Something in the button (right clicking it, triple-clicking it, a menu affordance that would drop something down next to it in situ, etc)." There are lots of tradeoffs in complexity here that people who know things about people should probably think through. :)

I think the answer to 3 is this will only come up if the website in a future visit ever calls navigator.geolocation.getCurrentPosition() ahead of the user pressing PEPC <geolocation></geolocation>

I'm not sure that's the case. I'm a weirdo, clearly, but I've certainly chosen to revoke capabilities I've given to sites in the past, and it's not crazy to imagine that other weirdo users would like to do the same.

in which case they'll be prompted (the old fashioned way?) and get the option to "Allow always" at that point, which makes me wonder: does PEPC even need to solve "Allow always"?

This is certainly the status quo behavior. But wouldn't it be ideal if we gated access to that API on a high-signal user gesture? Like, the one we receive from <geolocation>, for instance? For that to be possible, I think <geolocation something-other-than-persistent> is valuable.

(This folds into some of the points around the necessity of protecting the element's pixels that @martinthomson brought up yesterday, but blocking access to capabilities in the absence of something that provides a stronger signal of user intent (stronger than an arbitrary gesture somewhere in a document) seems like a pretty reasonable goal to aim for, and would go some distance towards mitigating the risk that users see prompts out of nowhere.)

[andypaicu]

I have updated the original description based on the various discussions and meetings. Please take a look.

[andypaicu]

I think the answer to 3 is this will only come up if the website in a future visit ever calls navigator.geolocation.getCurrentPosition() ahead of the user pressing PEPC <geolocation></geolocation>, in which case they'll be prompted (the old fashioned way?) and get the option to "Allow always" at that point — which makes me wonder: does PEPC even need to solve "Allow always"?

But if the site does that, it will mean that on the first visit as well (before the user had even interacted with the <geolocation> element) the user would be prompted with the regular prompt. Meaning that by not handling an "allow always" option we're encouraging a pattern that results in just as many prompts as the status quo.

The way I would prefer that this works is that sites only call gCP on next visits iff the permission is already granted:

1. When I visit a new site which has adopted the <geolocation> element, I don't see any prompt until I interact with it.
2. After I interact with it, if I pick the "always allow" choice, the site will get my location automatically when I visit the page at a later day.
3. At no point do I see a permission prompt that I have not initiated myself.

This could be done by the site calling permissions.query before their gCP call, though this does make the element more complicated to use in general.

Perhaps a better way to handle this would be: if the user picks the "always allow" option, on subsequent visits the <geolocation> element will immediately make the call to gCP and populate the location attribute without needing user interaction. In that way the user never sees a prompt that is initiated by the site and I think it also makes it easier to be used by developers: they just put this element in their site and wait until a location is ready.

[martinthomson]

The general direction this is heading seems good to me. As you note in the OP, there are a LOT of options for UX here, so we're going to need some time to work through those on our end.

I don't think that we should get too caught up in integration with getCurrentPosition. We can't remove it necessarily, but it can operate somewhat independently, provided that both it and <geolocation> both use the same underlying permissions. For that, I see that as being "granted" at different scopes: per-request (unlikely), per-visit (likely), and per-origin (maybe with a "remember this choice" option).

The watch attribute is interesting (I've been using "follow" instead, which seems more intuitive). That this might lead to spontaneous updates when location changes is the goal, but if we have an element that can receive interaction, it seems like updates could occur multiple times anyway. That leads me to conclude that maybe the value of watch is in suggesting that the browser ask for permission to have the location update. After all, a single permission interaction could produce a single location that is simply repeated at each interaction, not reflecting the real position of the device that might have moved since.