4.1 Privacy considerations for implementers of the Geofencing API

TODO

4.2 Privacy considerations for recipients of location information

TODO

5.1 Extensions to the ServiceWorkerRegistration interface

The Service Worker specification defines a ServiceWorkerRegistration interface, which this specification extends.

partial interface ServiceWorkerRegistration {
    readonly    attribute GeofenceManager geofencing;
};

5.2 GeofenceManager interface

The GeofenceManager interface defines operations that enable webapps to establish access to geofencing services.

dictionary GeofenceQueryOptions {
             DOMString? name;
};

dictionary GeofenceOptions {
             boolean includePosition = false;
};

[NoInterfaceObject]
interface GeofenceManager {
    Promise<Geofence>           add (GeofenceRegion initialRegion, optional GeofenceOptions options);
    Promise<sequence<Geofence>> getAll (optional GeofenceQueryOptions options);
    Promise<Geofence>           getById (DOMString id);
};

The add method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Run the following steps in parallel:
   1. If the total number of active geofences for all service worker registrations in the current origin is more than a user agent defined limit, reject promise with a DOMException whose name is "QuotaExceededError" and terminate these substeps. A user agent SHOULD allow at least 20 active geofences for an origin.
   2. Ask the user whether they allow the webapp to use geofences, unless a prearranged trust relationship applies or the user has already granted or denied permission explicitly for this webapp.
   3. If not granted, reject promise with a DOMException whose name is "PermissionDeniedError" and terminate these substeps.
   4. Let geofence be a new geofence.
   5. Set the geofence ID of the geofence to a newly generated value.
   6. Set the geographic region of the geofence to a GeofenceRegion instance of the same type and with the same attributes as the initialRegion passed to add.
   7. Set the include position flag of the geofence to options.includePosition, or false if no options were specified.
   8. Add geofence to the active geofences of the service worker registration associated with the webapp.
   9. If the current geographic position is inside the newly added region, fire a geofenceenter event.
   10. Resolve promise with a new Geofence instance representing the geofence.
3. Return promise.

If the includePosition attribute is set to true, GeofenceEvents for this registration will have a position attribute. When set to false, the position attribute will always be undefined.

The getAll method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Run the following steps in parallel:
   1. Let geofences be a new sequence.
   2. For each geofence in the active geofences associated with this service worker registration, run the following substeps:
      1. If options is passed, has a non-null name attribute, and that name is not equal to the name of the geofence, skip the rest of these substeps and continue with the next registration.
      2. Let geofence be a new Geofence instance representing the geofence.
      3. Append geofence to geofences.
   3. Resolve promise with geofences.
3. Return promise.

The getById method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Run the following steps in parallel:
   1. For each geofence in the active geofences associated with this service worker registration, run the following substeps:
      1. If the geofence ID of the current geofence is not equal to the passed in id, skip the rest of these substeps and continue with the next geofence.
      2. Let geofence be a new Geofence instance with attributes equal to those of the geofence.
      3. Resolve promise with geofence and abort the remainder of these substeps.
   2. If promise was not resolved, resolve promise with null.
3. Return promise.

5.3 Geofence interface

An instance of the Geofence interface represents a geofence.

interface Geofence {
    readonly    attribute DOMString      id;
    readonly    attribute GeofenceRegion region;
    Promise<boolean> remove ();
};

When getting the id attribute, the user agent MUST return the geofence ID of the geofence.

When getting the region attribute, the user agent MUST return the geographic region of this geofence.

The remove method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Run the following steps in parallel:
   1. If this geofence is not currently in the active geofences associated with a service worker registration, resolve promise with false and abort the remainder of these steps.
   2. Remove this geofence from the set of active geofences associated with the current service worker registration. No more events related to this geofence will be fired after this.
   3. Resolve promise with true.
3. Return promise.

5.4 GeofenceRegion interface

dictionary GeofenceRegionInit {
             DOMString? name;
};

[Exposed=(Window,Worker)]
interface GeofenceRegion {
    readonly    attribute DOMString name;
};

The name attribute MUST return the value it was initialized to. When the object is created, this attribute MUST be set to the value of the name property in the GeofenceRegionInit dictionary, or an empty string if that property wasn't set. A user agent MAY impose limits on the maximum size of the name attribute. If this limit is exceeded the constructor MUST throw a RangeError. If a user agent imposes a limit on the size of the name attribute, this limit SHOULD allow for at least 100 characters.

5.5 CircularGeofenceRegion interface

[Exposed=(Window,Worker)]
interface GeolocationPoint {
                attribute double latitude;
                attribute double longitude;
};

dictionary CircularGeofenceRegionInit {
             double latitude;
             double longitude;
             double radius;
};

[Constructor(CircularGeofenceRegionInit), Exposed=(Window,Worker)]
interface CircularGeofenceRegion : GeofenceRegion {
    readonly    attribute GeolocationPoint center;
    readonly    attribute double           radius;
};

The center attribute MUST return the value it was initialized to. When the object is created, this attribute MUST be set to a GeolocationPoint instance with its latitude and longitude properties set to the same values as those properties in the CircularGeofenceRegionInit dictionary. This represents the center of the circular region. Latitude must be between -90 and 90 inclusive. Longitude must be between -180 and 180 inclusive. If either of these properties is outside these ranges, the constructor will throw a RangeError.

The radius attribute MUST return the value it was initialized to. When the object is created, this attribute MUST be set to the value of the radius property in the CircularGeofenceRegionInit dictionary. This represents the radius of the circular region in meters.

The latitude property of a GeolocationPoint dictionary represents the latitude in circular degrees of a point.

The longitude property of a GeolocationPoint dictionary represents the longitude in circular degrees of a point.

5.6 Events

The Service Worker specification defines a ServiceWorkerGlobalScope interface, which this specification extends.

partial interface ServiceWorkerGlobalScope {
                attribute EventHandler ongeofenceenter;
                attribute EventHandler ongeofenceleave;
                attribute EventHandler ongeofenceerror;
};

The ongeofenceenter attribute is an event handler whose corresponding event handler event type is geofenceenter.

The ongeofenceleave attribute is an event handler whose corresponding event handler event type is geofenceleave.

The ongeofenceerror attribute is an event handler whose corresponding event handler event type is geofenceerror.

[Exposed=ServiceWorker]
interface GeofenceEvent : ExtendableEvent {
    readonly    attribute Geofence  geofence;
    readonly    attribute Position? position;
};

[Exposed=ServiceWorker]
interface GeofenceErrorEvent : ExtendableEvent {
    readonly    attribute Geofence       geofence;
    readonly    attribute unsigned short code;
    readonly    attribute DOMString      message;
};