Windows Phone 8: Tiles, lock, & notifications – //build/ 2-206

This blog post was authored by Thomas Fennel, a program manager on the Windows Phone developer tools team.

- Adam

It's a beautiful thing – the Windows Phone 8 Start screen is alive, personal, and it’s all about you, thanks to Live Tiles! The lock screen delivers delightful glance-and-go customization, with new ways to surface notifications and content in a way that connects with you.

But it doesn't get that way by magic and unicorn tears alone. It takes DEVELOPERS, DEVELOPERS, DEVELOPERS!

This year in my //build/ session I showed you an app I wrote that touches basically every feature in the Windows Phone 8 SDK related to using notifications in your app, with the platform’s various inputs, types, and templates. I’d like to take you on a brief tour of my demo app to explain what it does and how it does it. But, for those of you who are all about the code – and I know you’re out there – skip to the bottom of this post and download the source!

Notifications overview

A big focus this year in my //build/ session was to help people understand the conceptual breakdown of the way the Windows Phone notification platform works. We can break down the Windows Phone notification system into four logical, more manageable components: inputs, types, templates, and user experience (UX).

Inputs

Inputs are the first step in the notification process. You choose how you want to feed notification data into the notification system by choosing an input. Inputs can be:

• Scheduled – These inputs start the notification process by using a schedule, or a recurrence and interval. Scheduled notifications are a great way to execute a Tile update or an alarm/reminder whether or not your app is running.
• Local – Inputs you can use to send notifications while your app code is running. Your app code might be actively executing in the foreground as the user interacts with your app. Additionally, it could be that you have a background agent executing code periodically or even continuous background execution running in the background, depending on your scenario. In each of these scenarios, because it’s your app code that’s running, you can call the local notification APIs exactly as you would while your app is in the foreground.
• Push – With these inputs you can send near real-time info to a device in response to off-device events. For example, you can send a sports score update or a breaking news alert from your cloud service to your app using push notifications.

Types

Notification inputs feed into notification types. You can’t use all inputs with all types, so reference the diagram (above) to see how to use an input with the type. Types are sorted into three main categories:

• Alarms/Reminders– Modal notifications that take place at a certain date and time to help alert the user to an event. This is the only notification type not shown in The Final Countdown demo app.
• Tiles– Notifications that provide Live Tile functionality in Windows Phone. The Tile notification type is probably the most iconic and heavily used feature of the notification platform, and has the most flexibility for notification templates in the system. They should be delightful and engaging notifications targeted at enticing the user into the app.
• Toasts– Notifications designed to be interruptive to achieve targeted interaction with the user.

Templates

Notification types have different templates that define their visual and interaction experience with the end user. Tiles use Flip, Cycle, and Iconic templates, while toasts only have one template, simply called toast.

The Final Countdown app can do everything you see in one of the solid color blue boxes in the diagram above. Let’s take a quick tour of The Final Countdown app and explore the different features.

The Final Countdown Demo App

You’ll notice when you launch the app for the first time (assuming your environment is set to Debug mode) that it creates and displays a push channel URI. This is because The Final Countdown is set to receive push notifications as one of its input types. I use the dialog (left) while debugging so I can feel confident I’ve received the push URI. I’ll talk more about that later.

App navigation is very simple. It’s laid out on just two pivots, with no additional XAML pages. Live Tile features are on the first pivot page, and lock screen features are on the second pivot page.

“Tiles” pivot

The “tiles” pivot page shows five items, all related to using local input with the Tiles notification type, and the three Tile templates.

Primary performs operations on the primary Tile of the app – the Tile that you can pin by tapping and holding on The Final Countdown in the App list, and then pressing pin to start.

The first large button on the Primary line opens the lock screen settings for the device. This is how you pin to lock to have your app show a quick status or a detailed status. The next button is the same on each line and performs an update specific to the Tile template type. The last button on the line resets the Tile to its default state. Only the user can unpin the primary Tile.

On the Iconic, Flip, and Cycle lines of the pivot page, the first and third large buttons pin or delete the secondary Tile. The second button updates the Tile with new images, text, etc.

The last line on the page, Schedule, sets a ShellTileSchedule on the app’s primary Tile. The first large button starts the schedule, and the last button cancels it. Below Schedule are options to set the recurrence and the interval of the schedule. Check the code behind the start button to see more details. Also, one interesting note is that in Windows Phone 8, calling ShellTileSchedule.Start actually kicks off an immediate run of your scheduled update instead of making you wait for the first interval to come around as it did in Windows Phone 7.

You probably noticed that there is also a small button on each line that appears as a triangle pointing down. This opens advanced settings for each feature.

Use the C# button to form your Tile update using the properties of the specific class (IconicTileData, FlipTileData, or CycleTileData). Use the xml button to form the update using an XML payload instead. We’ve set breakpoints in the demo app to call this out as you try it. With the next two buttons you can choose to use local images from your package or images from a server you’ve designated in the cloud. There are “TODOs” and breakpoints in the demo app for the cloud download option. You’ll need to supply some of your own images to try out this option.

“Lock” pivot

The “lock” pivot can help you do each individual feature related to setting the background image on the lock screen.

Allow gives you the code to check whether you are the current lock screen background provider, but doesn’t actually set the lock screen. However, if you press Allow and then press Yes, the lock screen changes. This isn’t because the code changed the lock screen, but because now that the app is the lock screen background provider, the default lock screen image for the app, located at the root of the app package as DefaultLockScreen.jpg, has autotmatically been set by the sytem.

Set puts a predetermined image from the app package on the lock screen, and Pick uses the PhotoChooserTask to get an image from the phone’s Pictures app.

Reset returns the lock screen image to the app’s default image.

Live Lock is the most interesting button because it demonstrates how to use a background agent to compose a lock screen image and then set it on a periodic basis. The code behind that button kicks off the LaunchForTest method on the agent to start the process on demand.

After you press Live Lock, the best way to see the effect is to press Start and wait for the toast to notify you that the lock screen was updated. That toast also demonstrates how to use the local input with the toast type. If the update kicks off before you leave the app, you can tell it has run by looking in your Output window for the app to print “New current image set to...”, followed by “The program '[2292] HeadlessHost.exe' has exited”. Have a look at the OnInvoke code in ScheduledAgent.cs to see this all come together.

Hello push demo app

Another thing I showed in my //build/ talk this year was sending a push toast notification using a real Windows Azure website. Although in the talk I didn’t have time to give details about the push code and show all the push notification types, I provide the source for that Azure site here so you can do this on your own. And the best part about using Azure websites is that you can do it for free! So, now that you’ve got the demo app code, you can set it up and try it on a real website in the Azure cloud.

The Azure website publishing process is well explained on the Azure portal, so I’d like to instead focus on what you can do with this demo app code. The idea behind the hello push is to be a full toolbox of all the push notification types you can send to Windows Phone. By simply copying the channel URI for your app out of the debug output – like you can do with The Final Countdown – you can test the different notification scenarios you might want to support in your app. If you are using your own app, look at the MainPage() constructor in MainPage.xaml.cs in The Final Countdown demo app for a canonical way to set up push notifications in your app.

With this demo app, first, you can send a Tile update. We’ve tried to make it easy so that you can actually choose a template from the drop-down list and then fill in the properties, and hit send. In the code-behind we form all of those properties in the XML payload you would need to send to the push service. If you press the Preview button you can see the fully formed XML before you send it in case you want to copy it and modify it for use in the DIY Push box on the right side of the page. Note that the StandardTile option is really meant for Windows Phone 7, and FlipTile, IconicTile, and CycleTile are for Windows Phone 8. Also, remember that when you use CycleTile you can send a push to update the Tile, but your image references in that push must all be local image URIs in your app package (not isolated store or web images).

Toast Push lets you form a toast notification. In The Final Countdown app, you’re already set up for toast notifications, but if you’re using your own app, be sure you’ve called BindToShellToast() in your app code so that your app can receive toasts.

Text 1 is the bold text at the beginning of the toast and Text 2 is the non bold text that comes after it. You can use just one of these fields or both depending on your scenario.

You can use parameters to pass some name-value pairs to your app, and choose a page you can deep-link to in your app. For example, you could pass /MainPage.xaml?how=push_toast. Or if you just wanted to navigate to a Page2.xaml in your app, it would be just /Page2.xaml. Don’t forget XML escapes if you are combining name-value pairs and using an “&”. For example, you would send two pairs as ?how=push_toast&why=breaking_news.

Raw Push lets you send a raw notification of type 3 (for while your app is running in the foreground) or type 4 (for VoIP notifications). The raw push is quite simple in my hello push example and really just expects a string, but you can format XML to consume in your app if you want. The Final Countdown doesn’t handle raw type 4, but the ChatterBox app does if you want to try it with that.

The DIY Push option is for people who want to play with editing the XML from the various push templates on their own.

The two most important things to remember about the DIY Push option are to make sure you follow the pushXMLtemplatescarefully and to make sure you click the corresponding radio button for the push type you are sending.

Downloads

There are two samples that you can download:

• Tiles, Lock and Notifications for Windows Phone 8 - Azure Websites Sample (Hello Push Azure Websites):
  http://code.msdn.microsoft.com/Tiles-Lock-and-Notification-785d00b5
• Tiles, Lock and Notifications for Windows Phone 8 - Phone App Sample (The Final Countdown) :
  http://code.msdn.microsoft.com/Tiles-Lock-and-Notification-e63f498b

Wrap-up

I hope you have fun playing with this demo app and creating amazing Windows Phone apps. Remember to:

• Think about the notification inputs you want to use in your app and make sure they fit with your app’s capabilities.
• Think about the notification types you can take advantage of and make sure your scenarios and requirements meet the needs of the user.
• Design your templates to be beautiful and engaging.
• Make users love your app and love their Windows Phone!

A huge thanks to Matt Hidinger for cleaning up all the code and making it presentable to the world – he is a prince among men.