Windows Dev Center

Guidelines for geofencing apps (Windows Store apps using JavaScript and HTML)

Learn best practices for geofencing in building Windows Store apps using JavaScript and HTML.

Background and foreground listeners

In general, your Windows Store app does not need to listen for Geofence events both in the foreground and in a background task at the same time. The cleanest method for handling a case where you might need both is to let the background task handle the notifications. If you do set up both foreground and background geofence listeners, there is no guarantee which will be triggered first and so you must always call the ReadReports method to find out if an event has occurred. We also recommend that, if you have set up both foreground and background geofence listeners, you should unregister your foreground event listener whenever your app is not visible to the user and re-register your app when it becomes visible again. Here's some example code that registers for the visibility event.

 document.addEventListener("visibilitychange", onVisibilityChanged, false);

When the visibility changes, you can then enable or disable the foreground event handlers as shown here.

function onVisibilityChanged() {
    // NOTE: After the app is no longer visible on the screen and before the app is suspended
    // you might want your app to use toast notification for any geofence activity.
    // By registering for VisibiltyChanged the app is notified when the app is no longer visible in the foreground.

    if (document.msVisibilityState === "visible") {
        // register for foreground events
        Windows.Devices.Geolocation.Geofencing.GeofenceMonitor.current.addEventListener("geofencestatechanged", onGeofenceStateChanged);
        Windows.Devices.Geolocation.Geofencing.GeofenceMonitor.current.addEventListener("statuschanged", onGeofenceStatusChanged);
    } else {
        // unregister foreground events (let background capture events)
        Windows.Devices.Geolocation.Geofencing.GeofenceMonitor.current.removeEventListener("geofencestatechanged", onGeofenceStateChanged);
        Windows.Devices.Geolocation.Geofencing.GeofenceMonitor.current.removeEventListener("statuschanged", onGeofenceStatusChanged);

Checking for Internet access

If your app will need Internet access when a Geofence event occurs, you may want to check for Internet access before creating the geofence. If your app does not have Internet access, you can prompt the user to connect to the Internet before you set up the geofence or, if Internet access is not possible, you can avoid consuming the power that's needed for the geofencing location checks.

Checking the time stamp and current location

When an event indicates a change to an Entered or Exited state, check both the timestamp of the event and your current location. Various factors, such as the device being in standby or the user not noticing the notification, may affect when the event is actually processed by the user. For example, the following sequence may occur:

  • Your app creates a geofence and monitors the geofence for enter and exit events.
  • The user moves the device inside of the geofence, causing an enter event to be triggered.
  • Your app sends a notification to the user that they are now inside the geofence.
  • The user was busy and does not notice the notification until 10 minutes later.
  • During that 10 minute delay, the user has moved back outside of the geofence.
From the timestamp, you can tell that the action occurred in the past. From the current location, you can see that the user is now back outside of the geofence. Depending on the functionality of your app, you may want to filter out this event.

Location info unavailable

Remember that sometimes the device may not be able to get location info, even if permissions are turned on. The device may not contain a GPS radio, the GPS signal may be blocked or the Wi-Fi signal may not be strong enough. Make sure your app handles these cases gracefully and alerts the user if necessary.

Sizing your geofences

While GPS can provide the most accurate location info, geofencing can also use Wi-Fi or other location sensors to determine the user's current position. But using these other methods can affect the size of the geofences you can create. If the accuracy level is low, you probably do not want to create small geofences. For example, for an app that's designed for use indoors, where a GPS signal is most likely to be blocked, don't create geofences with a radius as small as 10 meters. This is bacause a Wi-Fi connection doesn't provide location info that's accurate enough to be useful. Also, if your geofence is running as a background task, you probably want to create a larger geofence because background tasks run only periodically; it would be possible for you to miss an Enter or Exit event entirely. If your app must use small geofences, it's best to advise users to use your app on a device with a GPS radio to ensure the best performance.

Related topics

Roadmap for Windows Store apps using JavaScript
Designing UX for apps
Quickstart: Setting up a geofence
Quickstart: Handling geofence notifications in the foreground
Quickstart: Listening for geofence events in the background
Quickstart: Handling geofence notifications from a background task



© 2015 Microsoft