Push Notifications Overview for Windows Phone
March 22, 2012
The Microsoft Push Notification Service in Windows Phone offers third-party developers a resilient, dedicated, and persistent channel to send data to a Windows Phone application from a web service in a power-efficient way.
The following diagram shows how your client application running on the phone can request a push notification URI from the Push client service (1). The Push client service then negotiates with the Microsoft Push Notification Service (MPNS) and returns a notification URI to your client application (2 and 3). Your client application can then send the URI to your cloud service (4). When your web service has information to send to your client application, it uses the URI in sending a push notification to the Microsoft Push Notification Service (5), which in turn routes the push notification to the application running on a Windows Phone device (6).
Depending on the format of the push notification and the payload attached to it, the information is delivered as raw data to the application, the application's Tile is visually updated, or a toast notification is displayed. The Microsoft Push Notification Service sends a response code to your web service after a push notification is sent indicating that the notification has been received and will be delivered to the device at the next possible opportunity. However, the Microsoft Push Notification Service does not provide an end-to-end confirmation that your push notification was delivered from your web service to the device.
The following notes contain information that is critical to having a successful implementation of push notifications.
Important Note:
|
|---|
|
We recommend setting up an authenticated web service to send your notifications to the Microsoft Push Notification Service, because communication occurs over an HTTPS interface for better security. Authenticated web services do not have a daily limit on the number of push notifications they can send. Unauthenticated web services, on the other hand, are throttled at a rate of 500 push notifications per subscription per day. For more information, see Setting Up an Authenticated Web Service to Send Push Notifications for Windows Phone. |
-
There is a limit of one push notification channel per application. This one channel can be used for all notification types available to the application. If your application exceeds this limit, an InvalidOperationException(PushNotificationChannelQuotaExceeded) exception is thrown. For more information, see Receiving Push Notifications for Windows Phone.
-
There is also a limit of 30 push notification channels per device. If your application attempts to register a push notification channel and the limit of 30 push notification channels per device has already been reached, an InvalidOperationException(PushNotificationChannelQuotaExceeded) exception is thrown. For more information, see Receiving Push Notifications for Windows Phone.
-
If you bind a push notification channel to a toast notification in your application, you must adhere to the requirements listed in the Push Notifications Application section in Additional Requirements for Specific Application Types and in section 2.9 of Application Policies.
-
Push notifications should not include personally identifiable information.
-
One challenge in development of applications that use push notifications is that the emulator is not subject to real-world conditions and will always have a reliable connection. Notifications that work reliably in the emulator may not work reliably on a real device because of fluctuating connectivity strength or incompatible network operator configurations. If a connection is not in a reliable state, developers may want to throttle back the number of notifications until a normal state is achieved. Developers should test their applications across multiple devices and mobile operators when feasible. By programming defensively around real-world connection states, developers can gracefully degrade functionality in their applications.
-
The maximum size of a notification is 1 KB for the header and 3 KB for the payload. Notifications exceeding these limits will be discarded and a WebException with a status of WebExceptionStatus.ProtocolError will be raised.
-
The Push client cannot work behind a SOCKS proxy. If the device transitions to a network that requires a SOCKS proxy, it will not be able to use the Push service. If you are testing on the emulator, you must configure the SOCKS proxy. For more information, see Proxy Support for Windows Phone Emulator.
There are three types of push notifications that a web service can use when sending information to an application: toast, Tile, and raw notifications.
Toast Notifications
A toast notification is displayed at the top of the screen to notify users of an event, such as a news or weather alert. The toast displays for about 10 seconds unless the user dismisses it with a flick to the right. If the user taps the toast, the application that sent the toast notification is launched.
The elements of a toast notification are:
-
Title. A boldface string that displays immediately after the application icon. This is defined as the Text1 property in the XML schema.
-
Content. A non-boldface string that displays immediately after the Title. This is defined as the Text2 property in the XML schema.
-
Parameter. A parameter value that is not displayed but passed to your application if the user taps on the toast. This parameter can indicate what page the application should launch to. It can also contain name-value pairs to pass to the application. This is defined as the Param property in the XML schema.
|
Important Note:
|
|---|
|
Toast notifications that set the Parameter property can be sent only to devices running Windows Phone OS 7.1 or greater. Sending a notification with the Parameter property to a Windows Phone OS 7.0 device will result in a PushErrorTypePayloadFormatInvalid error and the channel will be closed. |
The amount of text that can be displayed depends on the characters used in the toast message and the length of the Title, which is bolded, and Content, which is not bolded. If only a Title is set, then approximately 40 characters can be displayed before being truncated. If only a Content is set, then approximately 47 characters can be displayed. If a toast is split evenly between a Title and a Content, then approximately 41 characters can be displayed. Any text that does not fit on the toast will be truncated.
Windows Phone displays a small version of your application icon to the left of Title and Content. While you can define what icon is associated with your application, it is not possible to pass a different icon for a toast notification.
Tile Notifications
A Tile notification can be used to update a Tile on Start. For more information about Tile properties and how to update them, see Tiles Overview for Windows Phone. These properties on the front of a Tile can be updated using a Tile notification.
-
Title. A string indicating the title of the application. The Title must fit on a single line of text and should not be wider than the actual Tile. Approximately 15 characters will fit in the title before being truncated.
-
BackgroundImage. An image displayed on the front of the Tile. We recommend that you always have a background image on the front of the Tile.
-
Count (also known as Badge). An integer value from 1 to 99. If the value of Count is not set or it is set to 0, the circle image and value will not display in the Tile.
These properties on the back of a Tile can be updated using a Tile notification.
-
BackTitle. A string displayed at the bottom of the back of a Tile. The BackTitle must fit on a single line of text and should not be wider than the actual Tile. Approximately 15 characters will fit in the title before being truncated.
-
BackBackgroundImage. An image displayed on the back of the Tile.
-
BackContent. A string displayed in the body of the back of a Tile. Approximately 40 characters will fit in the Tile before being truncated.
|
Important Note:
|
|---|
|
Tile notifications that set the BackTitle, BackBackgroundImage, or BackContent properties or notifications that specify a secondary Tile by setting the Tile ID in the payload can be sent only to devices running Windows Phone OS 7.1 or greater. Sending a notification with these values to a Windows Phone OS 7.0 device will result in a PushErrorTypePayloadFormatInvalid error and the channel will be closed. |
Some additional notes on the images used for the BackgroundImage and the BackBackgroundImage properties:
-
Tile images can be either a .jpg or .png file.
-
Because of network variability and performance reasons, consider using local resources for Tile images.
-
Using a .png with transparent portions to the image will allow the user’s theme color to show through.
-
Tiles are 173 x 173 pixels. If the image you provide has different dimensions, it will be stretched to fit 173 x 173.
-
You can use a local or remote resource for the image. If you use a local resource, it must have been installed as a part of the XAP package.
-
If the user turns Tile notifications off, then the Tile should contain generic information. It should not contain any stale data, such as an outdated weather forecast or traffic report.
-
https is not supported for remote images.
-
Remote images are limited to 80 KB or less. If they are larger than 80 KB, they will not be downloaded.
-
Remote images must download in 30 seconds or less or they will not be downloaded.
-
If the BackgroundImage or BackBackgroundImage images fail to load for any reason, none of the other properties set in the update will be changed either.
Raw Notifications
You can use a raw notification to send information to your application. If your application is not currently running, the raw notification is discarded on the Microsoft Push Notification Service and is not delivered to the device.
