Recently I released a little open source project with the aim of making it easier for developers to write services that push information to Windows Phone 7 devices called MetroPimp.
This library is available via nuget and on bitbucket.
Based on a blog post I wrote when WP7 was still in beta, MetroPimp provides a simple and consistent API that allows you to push Toast, Tile (single and double sided) and Raw push notifications to WP7 devices using the Microsoft Push Notification Service (MPNS).
As developers who have tried this already may know, there is quite a bit of work that goes into setting up push notifications. First you have to register for notifications on the device by opening a channel. Then you have to get the URI provided by MPNS and send it to a service of your own. Lastly, using this URI you need to form XML packets and craft HTTP requests with the right headers to push the data to the device.
MetroPimp simplifies the last step of this process by providing a model that represents the messages you want to send to devices, a single method call to handle serializing the message and sending it up the wire and a simple result which, in the case of failure, identifies the reason for the failure and provides informative message.
Enough talking… show us the code!!!
The main entry point of MetroPimp is the Pusher class (which can be mocked via the IPusher interface). It has a single method named Send that accepts a Message and returns a SendMessageResponse. To create a Pusher, simply new it up (or inject it using your preferred IOC container).
var pusher = new Pusher();
The following sections will define the classes you can use to push various notification formats to a device. For more information on message formats, please refer to Sending Push Notifications for Windows Phone on MSDN.
Raw
To send raw data to the phone (i.e. a notification that is not a toast or tile update), create an instance of Raw and send it using the pusher.
var rawMessage = new Raw {
Uri = /* insert MPNS uri here */,
Content = "hello world!"
};
pusher.Send(rawMessage);
MPNS does not limit you to sending strings in the raw message. However, seeing as just about anything can be represented as a string, I decided this may be more universal. Under the covers, MetroPimp simply converts the string to its UTF8 representation and drops it into the request body.
For more information on sending and receiving raw notifications, refer to How to: Send and Receive Raw Notifications for Windows Phone on MSDN.
Toast
Sending a toast message is similar to sending a raw message in that you simply create an instance of a Toast object and pass it into Send. Toast has 3 fields that differ it from a raw:
- Text1 – The
first bit of bold text that appears in the toast (required)
- Text2 – The second bit of text that appears in the toast (optional)
- Param – A parameter string to be passed to the application if the user taps the notification (optional)
var toastMessage = new Toast {
Uri = /* insert MPNS uri here */,
Text1 = "Hello World!",
Text2 = "This is a toast.",
Param = "helloWorldToasted"
};
pusher.Send(toastMessage);
For more information on sending and receiving toast notifications, refer to How to: Send and Receive Toast Notifications for Windows Phone on MSDN.
Tile
Tile notifications can be specified to be either single or double sided tiles. As double sided tiles are only supported by WP7 Mango, the functionality has been split into two classes. Sending a single sided tile is done by specifying properties available on the Tile class.
- BackgroundImageUri – The URI to the background image for the tile. Can be either embedded or remote. (required)
- Title – The text to use as the title of the tile. (required)
- Count – The number to show in the blue bubble. Not defining or using 0 will clear the bubble. (optional)
var tileMessage= new Tile {
Uri = /* insert MPNS uri here */,
BackgroundImageUri = "background.png",
Title = "Hello World",
Count = 9
};
pushed.Send(tileMessage);
Double sided tiles are sent by specifying properties on the DoubleSidedTile class. This class has the same set of properties as Tile for the front side of the tile, along with the following properties for the back side:
- BackBackgroundImageUri – The URI to the background image for the back of the tile.
- BackTitle – The text to use as the title for the back of the tile.
- BackContent – The text to display over the top of the background image on the back of the tile.
var doubleSidedTileMessage = new DoubleSidedTile {
Uri = /* insert MPNS uri here */,
BackgroundImageUri = "background.png",
Title = "Hello World",
Count = 9,
BackBackgroundImageUri = "back_background.png",
BackTitle = "Hello Back",
BackContent = "This is the back"
};
pushed.Send(doubleSidedTileMessage);
For more information on sending and receiving toast notifications, refer to How to: Send and Receive Tile Notifications for Windows Phone on MSDN.
Auxiliary Properties
Raw, Toast, Tile and DoubleSidedTile all inherit the base Message class. This class provides the following optional properties to give you greater control over your notification messages:
- Id – a GUID value representing the message identifier.
- DeliveryInterval – Defines when the message should be delivered to the device. This can either be immediate (default), within 450 seconds or within 900 seconds.
SendMessageResponse
As soon as you’ve started trying to send notifications to devices, you’ll want to know if it gets through and/or why it failed. To handle this, Pusher.Send returns a SendMessageResponse object with the following properties:
- ErrorMessage – The message returned from MPNS on the HTTP response.
- MessageId – The
identifier of the message. Only included if specified when sending.
- HttpStatusCode – The HTTP status code (e.g. 200, 400, 401, etc.) of the HTTP response returned from MPNS.
- HttpStatusDescription – The description of the HTTP status code returned from MPNS.
- StatusCode – The actual status of the notification’s delivery returned from MPNS (i.e. Received, Queue Full, Suppressed or Dropped).
- DeviceConnectionStatusCode – The status of the device’s connection to MPNS (i.e. Connected, Temporarily Disconnected, Inactive or Disconnected).
- SubscriptionStatusCode – The status of the device’s subscription to MPNS (i.e. Active or Expired).
- DetailsStatusDescription – The detailed description of the notification message’s status given the HTTP status code, MPNS status code, connection and subscription status according to the MSDN documentation.
For more information on response codes, refer to Push Notification Service Response Codes for Windows Phone on MSDN.
so we were settled.
