diff --git a/index.html b/index.html index 3c35e4a..45c88cb 100644 --- a/index.html +++ b/index.html @@ -77,7 +77,7 @@

returns the device's actual location.

- If an end user [=check permission|grants permission=], + If an end user [=prompt the user to choose|grants permission=], Geolocation:

+

+ This specification provides two ways for users to share their location: +

+
+
+ precise position +
+
+ A position returned by the underlying location information source. By + default, any location data is considered precise, regardless of its + accuracy estimate, unless it has been explicitly coarsened by an + [=approximate location information source=] to be an [=approximate + position=]. +
+
+ approximate position +
+
+ A less [=precise position|precise=] representation of the user's + location. Instead of providing precise coordinates, an [=approximate + location information source=] returns a location that is coarsened + to a larger area, such as the nearest city, postal code, or a + predefined region. What constitutes a coarsened area is left to the + underlying system, which in turn can vary per jurisdiction. +

+ An [=approximate position=] is often sufficient for applications + that don't need to know the user's [=precise position=], for + example, a weather application that only needs a city-level + location. By sharing an [=approximate position=], users get the + benefit of a location-aware application without potentially + revealing their [=precise position=]. +

+
+
+

+ An approximate location information source is a location + information source that returns positions that have been intentionally + obfuscated to make it more difficult to recover the true location. +

Scope @@ -133,8 +172,12 @@

Get current position

- Request the user's current location. If the user allows it, you will - get back a position object. + A website can request a user's location, choosing either a [=precise + position=] or an [=approximate position=] via the + {{PositionOptions/accuracyMode}} member. During the [=prompt the user + to choose|permission request process=], the end-user determines the + actual level of accuracy to grant, which the [=user agent=] then uses + to provide the geographic position accordingly.

+

@@ -240,23 +293,34 @@

By default, the API always attempts to return a cached position so - long as it has a previously acquired position. In this example, we - accept a position whose age is no greater than 10 minutes. If the - user agent does not have a fresh enough cached position object, it - automatically acquires a new position. + long as it has a previously acquired position, and that position + matches the requested {{PositionOptions/accuracyMode}}. In this + example, we request a cached position whose age is no greater than 10 + minutes. If the user agent does not have a fresh enough cached + position object of the correct accuracy, it automatically acquires a + new position.

@@ -349,6 +413,17 @@

information also discloses the location of the user of the device, thereby potentially compromising the user's privacy.

+

+ The {{PositionOptions}}'s {{PositionOptions/accuracyMode}} member allows + websites to declare that they have no need for the user's [=precise + position=] and can function with only an [=approximate position=]. When + an application requests an [=approximate position=], an [=approximate + location information source=] is used. Even when a [=precise position=] + is requested, the user agent MAY provide an [=approximate position=] + instead (as defined in the [=acquire a position=] algorithm), for + example, if the user has only granted permission for approximate + accuracy. +

User consent @@ -405,6 +480,16 @@

stored, users need to be allowed to update and delete this information.

+

+ In line with this principle, recipients are strongly encouraged to + request the lowest level of location accuracy that is sufficient for + their application's functionality. For instance, if an application + only needs to know the user's city, it can indicate that to the user + by requesting an [=approximate position=], by setting the + {{PositionOptions/accuracyMode}} option to + {{AccuracyMode/"approximate"}}. This practice of data minimization is + a key aspect of respecting user privacy. +

The recipients of location information need to refrain from retransmitting the location information without the user’s express @@ -464,6 +549,27 @@

the relevant browser tab is closed.

+
+

+ Preventing Precise Location Reconstruction +

+

+ The [=approximate location information source=] used by the user agent + should take into account that a site, by repeatedly using the API, can + receive multiple [=approximate positions=]. Therefore it SHOULD, when + returning an [=approximate position=], implement measures that + mitigate the risk of a refinement attack, preventing the site from + potentially inferring a user's [=precise position=] by collecting and + correlating multiple, distinct [=approximate positions=]. +

+

+ The chosen accuracy is per request. A user agent that internally + shares one acquired position across concurrent requests coarsens it + for each {{AccuracyMode/"approximate"}} request when the position is + delivered, so an approximate request never receives a precise + position acquired for a concurrent request. +

+

@@ -689,17 +795,21 @@

-
  • Let |descriptor| be a new {{PermissionDescriptor}} whose - {{PermissionDescriptor/name}} is "geolocation". -
  • [=In parallel=]:
      -
    1. Set |permission| to [=request permission to use=] - |descriptor|. +
    2. Let |promptOptions| be the [=set=] « "approximate" » if + |options| {{PositionOptions/accuracyMode}} is + {{AccuracyMode/"approximate"}}, or the [=set=] « "approximate", + "precise" » if |options| {{PositionOptions/accuracyMode}} is + {{AccuracyMode/"precise"}}. +
      3. +
    3. Let |choice| be the result of [=prompting the user to + choose=] from |promptOptions| associated with + "geolocation".
    4. - If |permission| is "denied", then: + If |choice| is "denied", then:
      1. If |watchId| was passed, [=list/remove=] |watchId| from |watchIDs|. @@ -783,19 +893,36 @@

        |timeoutTime|, during which it tries to acquire the device's position by running the following steps:
          -
        1. Let |permission| be [=get the current permission state=] of - "geolocation". +
        2. Let |promptOptions| be the [=set=] « "approximate" » if + |options| {{PositionOptions/accuracyMode}} is + {{AccuracyMode/"approximate"}}, or the [=set=] « "approximate", + "precise" » if |options| {{PositionOptions/accuracyMode}} is + {{AccuracyMode/"precise"}}, and let |choice| be the result + of [=prompting the user to choose=] from |promptOptions| + associated with "geolocation". +
          3. -
        3. If |permission| is "denied": +
        4. If |choice| is "denied":
          1. Stop |timeout|.
          2. Do the user or system denied permission failure case step.
            3. +
          3. Terminate this algorithm. +
          5. -
        5. If |permission| is "granted": +
        6. Otherwise, run the following steps to determine |position|:
          1. Check if an emulated position should be used by running the following steps: @@ -817,8 +944,9 @@

        7. Let |position| be [=a new `GeolocationPosition`=] - passing |emulatedPositionData|, |acquisitionTime| and - |options|.{{PositionOptions/enableHighAccuracy}}. + passing |emulatedPositionData|, |acquisitionTime|, + |options|.{{PositionOptions/enableHighAccuracy}}, and + |choice|.
        8. [=Queue a task=] on the [=geolocation task source=] with a step that [=invokes=] @@ -841,7 +969,11 @@

        9. If |cachedPosition|'s {{GeolocationPosition/timestamp}}'s value is greater than - |cacheTime|, and + |cacheTime|, + |cachedPosition|.{{GeolocationPosition/[[accuracyMode]]}} + equals |choice|, and either + |cachedPosition|.{{GeolocationPosition/[[accuracyMode]]}} + is {{AccuracyMode/"approximate"}} or |cachedPosition|.{{GeolocationPosition/[[isHighAccuracy]]}} equals |options|.{{PositionOptions/enableHighAccuracy}}:
            @@ -856,165 +988,170 @@

          10. -
        10. Otherwise, if |position| is not |cachedPosition|, try to - acquire position data from the underlying system, optionally - taking into consideration the value of - |options|.{{PositionOptions/enableHighAccuracy}} during - acquisition. -
          11. -
        11. If the |timeout| elapses during acquisition, or acquiring - the device's position results in failure: +
        12. Try to acquire position data from the underlying system, + with the following considerations:
            -
          1. Stop the |timeout|. -
            2. -
          2. Go to dealing with - failures. -
            3. -
          3. Terminate this algorithm. +
          4. If |choice| is {{AccuracyMode/"approximate"}}, + acquire an [=approximate position=]. The + {{PositionOptions/enableHighAccuracy}} member is ignored.
            5. -
          -
          13. -
        13. If acquiring the position data from the - system succeeds: -
            -
          1. Let |positionData| be a [=map=] with the following - name/value pairs based on the acquired position data: -
            -
            - "latitude" -
            -
            - A {{double}} that represents the latitude - coordinates on the Earth's surface in degrees, - using the [[WGS84]] coordinate system. Latitude - measures how far north or south a point is from the - Equator. -
            -
            - "longitude" -
            -
            - A {{double}} that represents the longitude - coordinates on the Earth's surface in degrees, - using the [[WGS84]] coordinate system. Longitude - measures how far east or west a point is from the - Prime Meridian. -
            -
            - "altitude" -
            -
            - A {{double?}} that represents the altitude in - meters above the [[WGS84]] ellipsoid, or `null` if - not available. Altitude measures the height above - sea level. -
            -
            - "accuracy" -
            -
            - A non-negative {{double}} that represents the - accuracy value indicating the 95% confidence level - in meters. Accuracy measures how close the measured - coordinates are to the true position. -
            -
            - "altitudeAccuracy" -
            -
            - A non-negative {{double?}} that represents the - altitude accuracy, or `null` if not available, - indicating the 95% confidence level in meters. - Altitude accuracy measures how close the measured - altitude is to the true altitude. -
            -
            - "speed" -
            -
            - A non-negative {{double?}} that represents the - speed in meters per second, or `null` if not - available. Speed measures how fast the device is - moving. -
            -
            - "heading" -
            -
            - A {{double?}} that represents the heading in - degrees, or `null` if not available or the device - is stationary. Heading measures the direction in - which the device is moving relative to true north. -
            -
            -
            2. -
          2. Set |position| to [=a new `GeolocationPosition`=] - passing |positionData|, |acquisitionTime| and +
          3. If |choice| is {{AccuracyMode/"precise"}}, + acquire a [=precise position=], optionally taking into + consideration the value of |options|.{{PositionOptions/enableHighAccuracy}}.
            4. -
          4. Set [=this=]'s {{Geolocation/[[cachedPosition]]}} to - |position|. -
          14. +
        +

        2. +
      2. If the |timeout| elapses during acquisition, or acquiring the + device's position results in failure: +
        1. Stop the |timeout|.
          2. -
        2. [=Queue a task=] on the [=geolocation task source=] with - a step that [=invokes=] |successCallback| with « |position| » - and "`report`". +
        3. [=Deal with failure=]. +
          4. +
        4. Terminate this algorithm.
        3. -
      -
      -
      - Dealing with failures: -
      -
      -
        -
      • If acquiring a position fails, do one of the following - based on the condition that matches the failure: -
        -
        - User or system denied permission: +
      • If acquiring the position data from the + system succeeds: +
          +
        1. Let |positionData| be a [=map=] with the following + name/value pairs based on the acquired position data: +
          +
          + "latitude" +
          +
          + A {{double}} that represents the latitude coordinates + on the Earth's surface in degrees, using the [[WGS84]] + coordinate system. Latitude measures how far north or + south a point is from the Equator. +
          +
          + "longitude" +
          +
          + A {{double}} that represents the longitude coordinates + on the Earth's surface in degrees, using the [[WGS84]] + coordinate system. Longitude measures how far east or + west a point is from the Prime Meridian. +
          +
          + "altitude" +
          +
          + A {{double?}} that represents the altitude in meters + above the [[WGS84]] ellipsoid, or `null` if not + available. Altitude measures the height above sea + level. +
          +
          + "accuracy" +
          +
          + A non-negative {{double}} that represents the accuracy + value indicating the 95% confidence level in meters. + Accuracy measures how close the measured coordinates + are to the true position. +
          +
          + "altitudeAccuracy"
          -

          - [=Call back with error=] passing |errorCallback| and - {{GeolocationPositionError/PERMISSION_DENIED}}. -

          - + A non-negative {{double?}} that represents the altitude + accuracy, or `null` if not available, indicating the + 95% confidence level in meters. Altitude accuracy + measures how close the measured altitude is to the true + altitude.
          - Timeout elapsed: + "speed"
          - [=Call back with error=] with |errorCallback| and - {{GeolocationPositionError/TIMEOUT}}. + A non-negative {{double?}} that represents the speed in + meters per second, or `null` if not available. Speed + measures how fast the device is moving.
          - Data acquisition error or any other reason: + "heading"
          - [=Call back with error=] passing |errorCallback| and - {{GeolocationPositionError/POSITION_UNAVAILABLE}}. + A {{double?}} that represents the heading in degrees, + or `null` if not available or the device is stationary. + Heading measures the direction in which the device is + moving relative to true north.
          2. -
      -
      -
      +
    5. Set |position| to [=a new `GeolocationPosition`=] passing + |positionData|, |acquisitionTime|, + |options|.{{PositionOptions/enableHighAccuracy}}, and + |choice|. +
      6. +
    6. Set [=this=]'s {{Geolocation/[[cachedPosition]]}} to + |position|. +
      7. +
    +
    • +
  • Stop the |timeout|. +
    • +
  • [=Queue a task=] on the [=geolocation task source=] with a + step that [=invokes=] |successCallback| with « |position| » and + "`report`". +
    • + +
    +
    + Deal with failure: +
    +
    +
      +
    • If acquiring a position fails, do one of the following based + on the condition that matches the failure: +
      +
      + User or system denied permission: +
      +
      +

      + [=Call back with error=] passing |errorCallback| and + {{GeolocationPositionError/PERMISSION_DENIED}}. +

      + +
      +
      + Timeout elapsed: +
      +
      + [=Call back with error=] with |errorCallback| and + {{GeolocationPositionError/TIMEOUT}}. +
      +
      + Data acquisition error or any other reason: +
      +
      + [=Call back with error=] passing |errorCallback| and + {{GeolocationPositionError/POSITION_UNAVAILABLE}}. +
      +
      +
      • +
    +
    +

    @@ -1043,12 +1180,44 @@

    PositionOptions dictionary 

    +        enum AccuracyMode {
+          "precise",
+          "approximate"
+        };
+
         dictionary PositionOptions {
+          AccuracyMode accuracyMode = "precise";
           boolean enableHighAccuracy = false;
           [Clamp] unsigned long timeout = 0xFFFFFFFF;
           [Clamp] unsigned long maximumAge = 0;
         };
    +
    +

    + `accuracyMode` member +

    +

    + The accuracyMode member is used to request a specific + level of accuracy. +

    + + +

    `enableHighAccuracy` member @@ -1169,6 +1338,16 @@

    {{GeolocationPosition}} is [=a new GeolocationPosition|created=]. + + + [[\accuracyMode]] + + + An {{AccuracyMode}} that records the chosen {{AccuracyMode}} + when this {{GeolocationPosition}} is [=a new + GeolocationPosition|created=]. + +

    @@ -1269,10 +1448,15 @@

    A new `GeolocationPosition` is constructed with [=map=] - |positionData|, {{EpochTimeStamp}} |timestamp:EpochTimeStamp| and - boolean |isHighAccuracy| by performing the following steps: + |positionData|, {{EpochTimeStamp}} |timestamp:EpochTimeStamp|, + boolean |isHighAccuracy|, and {{AccuracyMode}} |accuracyMode| by + performing the following steps:

      +
    1. If |accuracyMode| is {{AccuracyMode/"approximate"}}, set + |positionData|["altitude"], |positionData|["altitudeAccuracy"], + |positionData|["speed"], and |positionData|["heading"] to null. +
    2. Let |coords:GeolocationCoordinates| be a newly created {{GeolocationCoordinates}} instance.
      3. @@ -1285,8 +1469,10 @@

    3. Return a newly created {{GeolocationPosition}} instance with its {{GeolocationPosition/coords}} attribute initialized to |coords| and {{GeolocationPosition/timestamp}} attribute initialized to - |timestamp|, and its {{GeolocationPosition/[[isHighAccuracy]]}} - internal slot set to |isHighAccuracy|. + |timestamp|, its {{GeolocationPosition/[[isHighAccuracy]]}} + internal slot set to |isHighAccuracy|, and its + {{GeolocationPosition/[[accuracyMode]]}} internal slot set to + |accuracyMode|.