The interfaces defined in this document are partial interfaces with respect to the Geolocation object defined in [[!GEOLOCATION-API]]. The primary extensions are related to geofencing and indoor positioning.

partial interface Geolocation

void GetCurrentProximity(in ProximityCallback successCallback, in WatchProximitySettings settings, in optional PositionErrorCallback errorCallback, in optional PositionOptions options)

The GetCurrentProximity() method takes up to four arguments. When called, it must immediately return and then asynchronously attempt to obtain the current location of the device and compare it to the geofence boundaries provided in settings. If the attempt is successful, the successCallback must be invoked (i.e. the handleEvent() operation must be invoked on the callback object) with a new Position object and a new ProximityState object, reflecting the current location of the device with respect to the geofence. If the attempt fails, the errorCallback must be invoked with a new PositionError object, reflecting the reason for the failure.

long watchProximity(in ProximityCallback successCallback, in WatchProximitySettings settings, in optional PositionErrorCallback errorCallback, in optional PositionOptions options)

The watchProximity() method takes up to four arguments. When called, it must immediately return a long value that uniquely identifies a watch operation and then asynchronously start the watch operation. This operation must first attempt to obtain the current proximity status of the device. If the attempt is successful, the successCallback must be invoked (i.e. the handleEvent() operation must be invoked on the callback object) with a new Position object and a new ProximityState object, reflecting the current location of the device. If the attempt fails, the errorCallback must be invoked with a new PositionError object, reflecting the reason for the failure. The watch operation then must continue to monitor the position of the device and invoke the appropriate callback every time the position changes sufficiently so that a breach of the geofence described in settings occurs. The watch operation must continue until the clearWatch method as defined in [[!GEOLOCATION-API]] is called with the corresponding identifier.

void handleEvent(in Position position, in ProximityState proximityState)

The handleEvent() function of a ProximityCallback callback function must be passed new Position and ProximityState objects when the watchProximity() method is called successfully and a breach of the geofence corresponding to the watch operation has been determined to occur.

This dictionary defines a circular geofence with a centroid and radius.

double latitude

Latitude of centroid for geofence. If not included, then current location latitude is used.

double longitude

Longitude of centroid for geofence. If not included, then current location longitude is used.

double radius

Radius of geofence in meters. If not included and no geofenceOption is provided, then the implementation will use a default value.

Position position

An object describing the position of the desired centroid. If included, the implementation must define as the geofence centroid the location represented by this object. This setting overrides both latitude amd longitude.

GeofenceOption geofenceOption

Option for setting non-circular geofence. If radius is provided then the implementation will ignore.

city

Option for setting geofence for roughly the scale of the a city with respect to the specified centroid

block

Option for setting geofence for roughly the scale of the a street block with respect to the specified centroid

building

Option for setting geofence for roughly the scale of the a building with respect to the specified centroid

room

Option for setting geofence for roughly the scale of the a room with respect to the specified centroid

The PositionError interface defined in [[!GEOLOCATION-API]] is extended to include geofencing error status.

const unsigned short WATCH_PROXIMITY_FAILED = 4

Error code for failure for proximity-based watch process

This interface defines a geofence breach event, where the device enters or leaves the boundary of the geofence defined by the WatchProximitySettings object passed into a getCurrentProximity() or watchProximity() method.

entering

If the ProximityState object is being returned to a ProximityCallback specified in a getCurrentProximity() function call and the device is currently inside the geofence, then it is set to this value. If the ProximityState object is being returned to a ProximityCallback specified in a watchProximity() function call and the device is currently entering inside the geofence, then it is set to this value.

leaving

If the ProximityState object is being returned to a ProximityCallback specified in a getCurrentProximity() function call and the device is currently outside of the geofence, then it is set to this value. If the ProximityState object is being returned to a ProximityCallback specified in a watchProximity() function call and the device is currently exiting the geofence, then it is set to this value.

unknown

The ProximityState object is set to this value if the User Agent is unable to determine the location of the device relative to the geofence.

Enhancements to the Position object defined in [[!GEOLOCATION-API]] are necessary when indoor location determination is available to the User Agent. In addition to latitude and longitude, additional information describing the location is returned in the Position object that further describes the location. If this information is unavailable, then the values of these new attributes must all be set to null.

readonly attribute double floorNumber

The floor number corresponding to the building at the current location. A value of 1.0 would indicate the first floor, 1.5 would indicate mezzanine, etc.

readonly attribute any venueID

Text that describes the venue corresponding to the current device location, e.g. The White House.

function updateDisplay(position, proxState) {
        // Displays geofence event
        if (proxState == "entering") {
            document.write('Entered geofence at ' + position.coords.latitude + ', ' + position.coords.longitude + '<br>');
            }
        else {
            if (proxState == "leaving") {
                document.write('Exited geofence at ' + position.coords.latitude + ', ' + position.coords.longitude + '<br>');
                }
            else {
                document.write ('Status unknown' + '<br>');
                }
            }

        }

    // Set geofence
    var gf = {latitude: 32.895732, longitude: -117.195861, radius: 10.5};

    // Request geofence
    var watchProximityId = navigator.geolocation.watchProximity(updateDisplay,gf);

    function buttonClickHandler() {
      // Cancel the geofence when the user clicks a button.
      navigator.geolocation.clearWatch(watchProximityId.id);
    }