Language: HTML | XAML

Quickstart: Listening for geofence events in the background (XAML)

Applies to Windows and Windows Phone

This topic will guide you through the steps of setting up a background task to listen for Geofence notifications in your Windows Runtime app using C++, C#, or Visual Basic.

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

Introduction

After your geofences have been created, you will have to add the logic to handle what happens when a geofence event occurs. Depending on the MonitoredStates that you have set up, you may receive an event when:

  • The user has entered a region of interest.
  • The user has left a region of interest.
  • The geofence has expired or been removed. Note that a background app is not activated for a removal event.

This topic describes how to set up a background task to alert your app when a geofence event occurs. But you can also handle events directly from your app when it is running. For more info, see Quickstart: Handling geofence notifications in the foreground and Guidelines for geofencing.

Listening for a geofence event in the background requires a number of steps:

  • Declare the background task in your app’s manifest.
  • Register the background task in your app. If your app needs internet access, say for accessing a cloud service, you can set a flag for that when the event is triggered. You can also set a flag to make sure the user is present when the event is triggered so that you are sure the user gets notified.
  • On Windows, you must have the user add the app to the lock screen in Windows Settings. If you are testing your application in the Microsoft Visual Studio simulator, add the application to the lock screen outside the simulator.
  • While your app is running in the foreground, prompt the user to grant your app location permissions.

Register for geofence state change events

In your app's manifest, under the Declarations tab, add a declaration for a location background task. To do this:

  • Add a declaration of type Background Tasks.
  • Set a property task type of Location.
  • Set an entry point into your app to call when the event is triggered.

Register the background task

The code below registers the geofencing background task. Remember that when the geofence was created, we checked for location permissions. Refer to Quickstart: Setting up a geofence for more information.


async private void RegisterBackgroundTask(object sender, RoutedEventArgs e)
{
    // Get permission for a background task from the user. If the user has already answered once,
    // this does nothing and the user must manually update their preference via PC Settings.
    BackgroundAccessStatus backgroundAccessStatus = await BackgroundExecutionManager.RequestAccessAsync();

    // Regardless of the answer, register the background task. If the user later adds this application
    // to the lock screen, the background task will be ready to run.
    // Create a new background task builder
    BackgroundTaskBuilder geofenceTaskBuilder = new BackgroundTaskBuilder();

    geofenceTaskBuilder.Name = SampleBackgroundTaskName;
    geofenceTaskBuilder.TaskEntryPoint = SampleBackgroundTaskEntryPoint;

    // Create a new location trigger
    var trigger = new LocationTrigger(LocationTriggerType.Geofence);

    // Associate the locationi trigger with the background task builder
    geofenceTaskBuilder.SetTrigger(trigger);

    // If it is important that there is user presence and/or
    // internet connection when OnCompleted is called
    // the following could be called before calling Register()
    // SystemCondition condition = new SystemCondition(SystemConditionType.UserPresent | SystemConditionType.InternetAvailable);
    // geofenceTaskBuilder.AddCondition(condition);

    // Register the background task
    geofenceTask = geofenceTaskBuilder.Register();

    // Associate an event handler with the new background task
    geofenceTask.Completed += new BackgroundTaskCompletedEventHandler(OnCompleted);

    BackgroundTaskState.RegisterBackgroundTask(BackgroundTaskState.LocationTriggerBackgroundTaskName);

    switch (backgroundAccessStatus)
    {
    case BackgroundAccessStatus.Unspecified:
    case BackgroundAccessStatus.Denied:
        rootPage.NotifyUser("This application must be added to the lock screen before the background task will run.", NotifyType.ErrorMessage);
        break;

    }
}




  • Applies to Windows Phone

Note  On Windows Phone, you must call RequestAccessAsync, but no prompt is shown to the user and your app does not need to be pinned to the lock screen. The call is simply required to alert the system that your app is registering a background task.

Related topics

Roadmaps
Roadmap for Windows Runtime apps using C# and Visual Basic
Roadmap for Windows Runtime apps using C++
Designing UX for apps
Tasks
Quickstart: Setting up a geofence
Quickstart: Handling geofence notifications in the foreground
Quickstart: Handling geofence notifications from a background task
Reference
Geoshape
Geofence
Geolocator
Other resources
Guidelines for geofencing

 

 

Show:
© 2014 Microsoft