Quickstart: Setting up a geofence (HTML)

Applies to Windows and Windows Phone

This topic will guide you through the steps of setting up a Geofence in your Windows Runtime app using JavaScript.

Roadmap: How does this topic relate to others? See:

Introduction

There are a number of steps to take when setting up your Geofence. Besides defining the region of interest, you also need to make sure you have the proper location permissions. Finally, you need to set up an event handler in case the user changes those permissions while your app is running.

Check for location permissions

First you may want to add code to your app during initialization to get the location. On Windows, the first time your app uses the API to get the current location, the system will prompt the user for location permission. If your app doesn't have permission from the user, then alert the user. Note that you can still set up a Geofence without location permissions but you won’t receive any notifications until the permissions have been enabled.


    function initialize() {

        promise = geolocator.getGeopositionAsync();
        promise.done(
            function (pos) {
                var coord = pos.coordinate;

            },
            function (err) {
            // handle situations where location permissions are not granted to your app
            }
        );

    }





Listen for location permission changes

  • Applies to Windows

Note  This section applies to Windows only.

Next you want to be sure to register for permission change events, in case the user decides to turn the location permissions off for some reason. First add the event handlers to your initialization method:



var accessInfo = null;
accessInfo = DeviceAccessInformation.createFromDeviceClass(Enumeration.DeviceClass.location);
accessInfo.addEventListener("accesschanged", onAccessChanged);



Then handle the permissions change to let the user know that geofencing will no longer work if location permissions are turned off:


function onAccessChanged(args) {
    var eventDescription = getTimeStampedMessage("Device Access Status");
    var item = null;

    if (DeviceAccessStatus.deniedByUser === args.status) {
        eventDescription += " (DeniedByUser)";

        WinJS.log && WinJS.log("Location has been disabled by the user. Enable access through the settings charm.", "sample", "status");
    } else if (DeviceAccessStatus.deniedBySystem === args.status) {
        eventDescription += " (DeniedBySystem)";

        WinJS.log && WinJS.log("Location has been disabled by the system. The administrator of the device must enable location access through the location control panel.", "sample", "status");
    } else if (DeviceAccessStatus.unspecified === args.status) {
        eventDescription += " (Unspecified)";

        WinJS.log && WinJS.log("Location has been disabled by unspecified source. The administrator of the device may need to enable location access through the location control panel, then enable access through the settings charm.", "sample", "status");
    } else if (DeviceAccessStatus.allowed === args.status) {
        eventDescription += " (Allowed)";

        // clear status
        WinJS.log && WinJS.log("", "sample", "status");
    } else {
        eventDescription += " (Unknown)";

        WinJS.log && WinJS.log("Unknown device access information status", "sample", "status");
    }

    addEventDescription(eventDescription);
}



  • Applies to Windows Phone

Note  Note that on Windows Phone, you determine if the user has disabled location in Settings by checking the LocationStatus property. If the value is Disabled, then location is disabled.

Create the geofence

Now you are ready for define and set up a geofence. Some of the values that can be set for a geofence are:

  • An Id to identify it.
  • The circular region of interest, defined by the Geoshape.
  • The MonitoredStates, which indicate what geofence events you want to receive notifications for - entering the defined region, leaving the defined region, or removal of the geofence.
  • A SingleUse flag, which will remove the geofence once all the states the geofence is being monitored for have been met.
  • A DwellTime, which indicates how long the user must be in or out of the defined area before the enter/exit events are triggered.
  • The StartTime, which indicates when to start monitoring the geofence.
  • The Duration to monitor the geofence for.


function generateGeofence() {
    var geofence = null;

    try {
        var fenceKey = nameElement.value;

        var position = {
            latitude: decimalFormatter.parseDouble(latitude.value),
            longitude: decimalFormatter.parseDouble(longitude.value),
            altitude: 0
        };
        var radiusValue = decimalFormatter.parseDouble(radius.value);

        // the geofence is a circular region
        var geocircle = new Windows.Devices.Geolocation.Geocircle(position, radiusValue);

        var singleUse = false;

        if (geofenceSingleUse.checked) {
            singleUse = true;
        }

        // want to listen for enter geofence, exit geofence and remove geofence events
        var mask = 0;

        mask = mask | Windows.Devices.Geolocation.Geofencing.MonitoredGeofenceStates.entered;
        mask = mask | Windows.Devices.Geolocation.Geofencing.MonitoredGeofenceStates.exited;
        mask = mask | Windows.Devices.Geolocation.Geofencing.MonitoredGeofenceStates.removed;

        var dwellTimeSpan = new Number(parseTimeSpan(dwellTimeField, defaultDwellTimeSeconds));
        var durationTimeSpan = null;
        if (durationField.value.length) {
            durationTimeSpan = new Number(parseTimeSpan(durationField, 0));
        } else {
            durationTimeSpan = new Number(0); // duration needs to be set since start time is set below
        }
        var startDateTime = null;
        if (startTimeField.value.length) {
            startDateTime = new Date(startTimeField.value);
        } else {
            startDateTime = new Date(); // if you don't set start time in JavaScript the start time defaults to 1/1/1601
        }

        geofence = new Windows.Devices.Geolocation.Geofencing.Geofence(fenceKey, geocircle, mask, singleUse, dwellTimeSpan, startDateTime, durationTimeSpan);
    } catch (ex) {
        WinJS.log && WinJS.log(ex.toString(), "sample", "error");
    }

    return geofence;
}



Related topics

Roadmaps
Roadmap for Windows Runtime apps using JavaScript
Designing UX for apps
Tasks
Quickstart: Handling geofence notifications in the foreground
Quickstart: Listening for geofence events in the background
Quickstart: Handling geofence notifications from a background task
Reference
Geoshape
Geofence
Geolocator
Other resources
Guidelines for geofencing

 

 

Show:
© 2014 Microsoft