Geofencing

Geofencing APIs enables scenarios such as notifications when the device enters or leaves an app-specified geographic region. This makes possible app scenarios such as displaying a reminder when the user arrives at home or notifying the user of deals at stores in area he is currently. Let’s see how to setup the geofence an respond on the geofencing events. First of all, the app must declare a “Location” capability in application manifest:

Next, the good idea is to check access status to the Geolocator:

try

{

//Get geolocator

geolocator = new Geolocator();

//Optionally

await geolocator.GetGeopositionAsync().AsTask(token);

}

catch (UnauthorizedAccessException)

{

//...

}

This code ensures that user enabled location services and helps adjust app flow in case he doesn’t. Please note, that app can still set up a Geofence without location permissions but it won’t receive any notifications until the permissions have been enabled.

Setting up a geofence is pretty easy – every app has a collection of geofences identified by Id and defined by region of interest. In addition, the geofence definition contains properties such as MonitoredStates (which indicate what geofence events you want to receive notifications for), DwellTime (indicates how long the user must be in or out of the defined area before the enter/exit events are triggered), StartTime (indicates when to start monitoring the geofence) and others.

//Define how long user should be in or our of area of interest before the event is raised

var dwellTime = TimeSpan.FromSeconds(5);

//Create a new object and add it to the collection of geofences

var geofence = new Geofence(id, geocircle, mask, false, dwellTime);

GeofenceMonitor.Current.Geofences.Add(geofence);

Geofence object supports different types of areas – in the code snippet above I used a circular area, but you can define rectangular area (GeoboundingBox), series of geographic points (Geopath) or even single geographic point (Geopoint).

Also, it could be a good practice to check the presence of specific geofence in the geofences collection as they are preserved between application sessions by system-wide GeofenceMonitor component. The geofences are not removed from the collection automatically and must be manually removed by the app.

When geofence is added to the collection, the app could subscribe to the state changes and read the report from the reports:

//Each report conteains info about new state, position and geofence object

var state = report.NewState;

var geofence = report.Geofence;

if (state == GeofenceState.Entered)

//App logic...

elseif (state == GeofenceState.Exited)

//App logic...

}

});

}

Geofencing could be debugged via new WP emulator – I will talk about the emulator later in this post.

Sharing

Additional new feature supported on WP8.1 form Win8.x s Sharing. While the UI is different as WP doesn’t support charms, the API is the same. To share from the app, simply. It is initiated by the following line of code:

//Call this to get an exception if the background task completed event has reported an error

args.CheckResult();

Debug.WriteLine("Task completed succesfully");

//...

}

catch

{

Debug.WriteLine("Task failed");

//...

}

}

Visual Studio comes handy when need to debug the background tasks as it provides a simulation of lifecycle events and background tasks through the “Debug Location” menu and helps to simulate the trigger that launches the background task under the debugger:

Push Notifications, Tiles and Toasts

WP8.1 supports different type of push notifications depending on the technology used to develop the app. If the app is SL8.1 app, the dev can choose “good-old” WP approach using MPN (Microsoft Push Notification Server) or opt-in newer WNS (Windows Notification Server) approach which is shared with Win8.1. This selection is done in WPAppManifest – the old portion of SL8.1 phone app:

This selection influences which types of tiles will be supported by the app. The MPN selection will leave the app with WP8.0 compatible tiles selection (Flip, Cycle and Iconic) and related APIs. The WNS selection will force the app to use WinRT tiles and APIs.

If the app is WinRT app, then only WNS push notifications are supported. WNS supports delivering Toasts, Tiles, Badges and Raw XML push notifications exactly like on Win8.1.

Working with either MPN or WNS and preparing the app to work with either one of them will follow exact pattern of WP8.0 app (for MPN) or Win8.x app (for WNS). For full info, please refer to the relevant APIs/documentation.

While MPN tiles/toast selection are not changed from WP8.0, the WNS tiles and toasts are converged with Win8.1. Let’s overview the the converged toasts and tiles and how to create manage them on WP8.1.

Toasts & Action Center

Technically, WP8.1 supports all toast templates from Win8.1, but since the toast notification is presented differently on the device all templates being rendered the same. It means that regardless to the selected toast template form ToastTemplateType enum, user will be presented with the same standard WP toast experience:

The toast could be raised from active app, push notification or while running in background task. Following is the sample of how to show toast notification from the running app:

In addition to simply showing the notification, WP8.1 enables app to manage them through Action Center. Action Center enable app to show/present up to 20 notifications and persist them up to 7 days in the Action Center. In the Action Center user can chase the notification (tap to open the app) and remove notification (single, all, group).

Developer can manage app notifications by adding a new notification, removing or replacing existing notification, grouping and tagging notifications for easy management, set an expiration time on the notification and send a “Ghost” notification which is shown only as an icon in Action Center but not pops up as regular toast. The following code snippet shows how to manage the notifications from the app:

//Specify a "Ghost" mode - this notification will be shown only as an icon and not as popup

toast.SuppressPopup = true;

//Show the toast

ToastNotificationManager.CreateToastNotifier().Show(toast);

//...

//Remove all app notifications

ToastNotificationManager.History.Clear();

//Remove specific notification by the tag

ToastNotificationManager.History.Remove("Sample_toast");

//Remove specific notification by the tag from specific group

ToastNotificationManager.History.Remove("Sample_toast", "Blog Post");

//Remove all notifications from the group

ToastNotificationManager.History.RemoveGroup("Blog Post");

The “Ghost” notification produced from the code above looks like the following:

To show tiles the app must be set as “Toast capable” in the application manifest:

Tiles & Badges

The tile feature is more “visually” converged, share about 40 tile templates with Win8.1 platform but still have some minor UI differences to support native WP UX.

First, WP still supports only 3 sizes of the tiles – this means that Square 310×310 (aka Huge) tile is not supported on WP.

Next, while the APIs are exactly the same, the presentation of the tiles is different. For example “peek” animation on WP presented as flip animation, “Image collection” on WP looks exactly like Cycle tile, “Block” looks like Iconic tile.

Lastly, badges shown show platform specific UI and WP doesn’t support all badge types, but only numbers and “alert” + “attention” glyphs.

The code below shows how to update main app tile using new converged templates:

//Create a tile XML -- could be create using different approaches such as TileTemplateType enum, NotificationExtensions from Win8 SDK, etc.

Secondary tiles use the same templates and same APIs as on Win8.1 and produce same type of visuals as described above.

Finally, WP8.1 supports periodical tile updates. It requires some web-based resource that generates tile response and could be used by the app for periodic tile update. Tile update frequency set in application manifest, similarly to Win8.1:

Note: this tile update mechanism could be used also to update the app’s tile on install as the tile will be updated right after installing the app with such declaration in application manifest.

WP Emulator & Tools

New version of WP SDK brings improved WP emulator and few changes/improvements in the tools. What’s new there?

First of all – many different WP 8.1 emulator images:

Next – new project templates, that help to create either Silverlight or WinRT apps:

The solution includes phone-specific app, windows-specific app and shared part that will be compiled in both projects. This shared project can include XAML and code files, assets, folders, etc. The code in “Shared” project is not a portable library code, but full WinRT code to be compiled with target app similarly to source file linking.

While editing shared code, the VS provides scope switch so the same file could be “seen” using target-platform definitions such as constants, platform-specific references, conditional compilation symbols, etc:

To distinguish between two platforms in shared code file the project defines a conditional compilation symbols:

WINDOWS_APP for Win8.1

WINDOWS_PHONE_APP for WP8.1

In such case the context switch described above helps to visually distinguish between active/inactive code

Same switch exists also in XAML editor:

In addition to editor improvements, the SDK supplies new set of developer tools, that can help with fine tuning the app:

The tools are working with either emulator or real device and can monitor specific areas of the app: