1 out of 2 rated this helpful - Rate this topic

Sending Push Notifications for Windows Phone

Windows Phone

March 22, 2012

After your Windows Phone client application has registered for notifications, you can send notifications to it. Typically, this is done with a web service that keeps a collection of URIs to send notifications to, but it also can be done with any application that can send messages to the Microsoft Push Notification Service. To see sample code implementing the sending of push notifications, see How to: Send and Receive Toast Notifications for Windows Phone, How to: Send and Receive Tile Notifications for Windows Phone, and How to: Send and Receive Raw Notifications for Windows Phone.

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.

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.

To send push notifications, your web service or application must:

Create a POST message for each Windows Phone device to which you want to send a notification.
Form the message for the appropriate notification type. The following sections describe the message formats for toast, Tile, and raw notification messages. You can post only one notification type (Tile, toast, or raw) to the server at a time. If you want to send multiple notification types to the same client device at the same time, you must create separate POST messages for each notification type.
Downgrade messages correctly for Windows Phone OS 7.0 clients by not using properties that are unavailable on Windows Phone OS 7.0, specifically, the Parameter property for toast notifications and BackTitle, BackBackgroundImage, BackContent or Tile ID properties for Tile notifications. We recommend that you send the device OS version information at the same time you are registering the device URI information with your web service.
Post the messages to the Microsoft Push Notification Service.
Get the response from the Microsoft Push Notification Service and react accordingly.

Custom HTTP Headers

The custom HTTP headers can include this information:

Header	Specification	Description
MessageID	Copy "X-MessageID"":"1*MessageIDValue MessageIDValue = STRING (uuid) //For example: X-MessageID:<UUID>	The notification message ID associated with the response. If this header is not added to the POST request, the Microsoft Push Notification Service omits this header in the response.
NotificationClass	Copy ”X-NotificationClass””:”1*NotificationClassValue NotificationClassValue = DIGIT //For example: X-NotificationClass:1	The batching interval that indicates when the push notification will be sent to the application from the Push Notification Service. See the tables in the toast, Tile, and raw notification sections for possible values for this header. If this header is not present, the message will be delivered by the Push Notification Service immediately.
Notification Type	Copy “X-WindowsPhone-Target””:”1*NotificationTypeValue NotificationTypeValue = STRING //For example: X-WindowsPhone-Target:toast	The type of push notification being sent. Possible options are Tile, toast, and raw. If this header is not present, the push notification will be treated as a raw notification. For more information, see Push Notifications Overview for Windows Phone.
CallbackURI	Copy "X-CallbackURI"":"1*CallbackURIValue CallbackURIValue = STRING (URI) //For example: X-CallbackURI: <URI>	The notification channel URI that the registered callback message will be sent to when a certain event is triggered. This custom header is allowed only when registering a callback message with an authenticated web service. For more information about registering a callback message, see How to: Set up a Callback Registration Request for Windows Phone. For more information about authenticated web services, see Setting Up an Authenticated Web Service to Send Push Notifications for Windows Phone.

Special Characters

The following characters should be encoded as shown in the table when used in a Tile or toast payload:

Character	XML encoding
<	<
>	>
&	&
‘	'
“	"

Notification Payloads

Notifications can have the following types of payload:

Toast Notification Payload

Use the following HTTP headers:

Copy

sendNotificationRequest.ContentType = "text/xml";
sendNotificationRequest.Headers.Add("X-WindowsPhone-Target", "toast");
sendNotificationRequest.Headers.Add("X-NotificationClass", "<batching interval>");

The following table describes the values that the batching interval can have.

Value	Delivery interval
2	Immediate delivery.
12	Delivered within 450 seconds.
22	Delivered within 900 seconds.

The payload should contain the following.

Copy


string toastMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<wp:Notification xmlns:wp=\"WPNotification\">" +
    "<wp:Toast>" +
        "<wp:Text1><string></wp:Text1>" +
        "<wp:Text2><string></wp:Text2>" +
        "<wp:Param><string></wp:Param>" +
    "</wp:Toast>" +
"</wp:Notification>";

<Text1> and <Text2> are in a string format.

The following formats are allowed for the <Param> value:

/page1.xaml – Defines the page to navigate to in the application when it is started. It must begin with a “/”.
/page1.xaml?value1=1234 &value2=9876 – Defines the page to navigate to when the application is started, along with name/value pairs of information. It must begin with a “/”.
?value1=1234 &value2=9876 – Contains name/value pairs of information passed to the default start page of the application. It must begin with a “?”.

Important Note:
The value in the <Param> tag must 256 characters or less. Exceeding this limit will cause a PushErrorTypeMessageBadContent error to be returned in the ErrorOccurred event handler.

The values of parameters are typically parsed out of the toast payload in the OnNavigatedTo event handler after the user has clicked on the toast and navigated to the indicated page of the client application running on the device.

Copy

        protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
        {
            base.OnNavigatedTo(e);

            string strVal1 = this.NavigationContext.QueryString["value1"];
            string strVal2 = this.NavigationContext.QueryString["value2"];

        }

Tile Notification Payload

Use the following HTTP headers.

Copy

sendNotificationRequest.ContentType = "text/xml";
sendNotificationRequest.Headers.Add("X-WindowsPhone-Target", "token");
sendNotificationRequest.Headers.Add("X-NotificationClass", "<batching interval>");

The following table describes the values that the batching interval can have.

Value	Delivery interval
1	Immediate delivery.
11	Delivered within 450 seconds.
21	Delivered within 900 seconds.

The payload should contain the following.

Copy


string tileMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<wp:Notification xmlns:wp=\"WPNotification\">" +
    "<wp:Tile Id=\”Navigation Uri of the Tile to update\”>" +
        "<wp:BackgroundImage><front side of Tile background image path></wp:BackgroundImage>" +
        "<wp:Count><front side of Tile count></wp:Count>" +
        "<wp:Title><front side of Tile title></wp:Title>" +
        "<wp:BackBackgroundImage><back side of Tile image path></wp:BackBackgroundImage>"+
        "<wp:BackTitle><back side of Tile title></wp:BackTitle>"+
        "<wp:BackContent><back side of Tile text></wp:BackContent>"+
    "</wp:Tile> " +
"</wp:Notification>";

The Id designates which Tile to update, if an application has secondary Tiles. To update the Application Tile, the Id can be omitted:

Copy


string tileMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<wp:Notification xmlns:wp=\"WPNotification\">" +
  "<wp:Tile >" +
    "<wp:BackgroundImage>" + TextBoxBackgroundImage.Text + "</wp:BackgroundImage>" +
    "<wp:Count>" + TextBoxCount.Text + "</wp:Count>" +
    "<wp:Title>" + TextBoxTitle.Text + "</wp:Title>" +
    "<wp:BackBackgroundImage>" + TextBoxBackBackgroundImage.Text + "</wp:BackBackgroundImage>" +
    "<wp:BackTitle>" + TextBoxBackTitle.Text + "</wp:BackTitle>" +
    "<wp:BackContent>" + TextBoxBackContent.Text + "</wp:BackContent>" +
  "</wp:Tile> " +
"</wp:Notification>";

Otherwise the Id should contain the exact navigation Uri of the secondary tile:

Copy


string tileMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<wp:Notification xmlns:wp=\"WPNotification\">" +
  "<wp:Tile ID=\"/SecondaryTile.xaml?DefaultTitle=FromTile\">" +
    "<wp:BackgroundImage>" + TextBoxBackgroundImage.Text + "</wp:BackgroundImage>" +
    "<wp:Count>" + TextBoxCount.Text + "</wp:Count>" +
    "<wp:Title>" + TextBoxTitle.Text + "</wp:Title>" +
    "<wp:BackBackgroundImage>" + TextBoxBackBackgroundImage.Text + "</wp:BackBackgroundImage>" +
    "<wp:BackTitle>" + TextBoxBackTitle.Text + "</wp:BackTitle>" +
    "<wp:BackContent>" + TextBoxBackContent.Text + "</wp:BackContent>" +
  "</wp:Tile> " +
"</wp:Notification>";

To clear the value for a Tile property, set the Action attribute to Clear for the property. Note that you cannot clear the BackgroundImage property because you should always have a background image set on the front of the Tile.

Copy

string tileMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
    "<wp:Notification xmlns:wp=\"WPNotification\">" +
        "<wp:Tile Id=\"Navigation URI of the tile to update\">" +
            "<wp:BackgroundImage> </wp:BackgroundImage>" +
            "<wp:Count Action=\"Clear\"></wp:Count>" +
            "<wp:Title Action=\"Clear\"></wp:Title>" +
            "<wp:BackBackgroundImage Action=\"Clear\"></wp:BackBackgroundImage>"+
            "<wp:BackTitle Action=\"Clear\"></wp:BackTitle>"+
            "<wp:BackContent Action=\"Clear\"></wp:BackContent>"+
        "</wp:Tile> " +
    "</wp:Notification>";

Raw Notification Payload

Use the following HTTP headers:

Copy

sendNotificationRequest.ContentType = "text/xml";
sendNotificationRequest.Headers.Add("X-NotificationClass", "<batching interval>");

The following table describes the values that the batching interval can have.

Value	Delivery interval
3	Immediate delivery.
13	Delivered within 450 seconds.
23	Delivered within 900 seconds.

The structure of the payload is defined by the application. The following code shows an example.

Copy


string tileMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
    "<root>" +
        "<Value1><UserValue1><Value1>" +
        "<Value2><UserValue2><Value2>" +
    "</root>"

You can also just pass a byte stream. The following code shows an example.

Copy

new byte[] {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};

Other Resources

Push Notifications Overview for Windows Phone

Receiving Push Notifications for Windows Phone

How to: Send and Receive Toast Notifications for Windows Phone

How to: Send and Receive Tile Notifications for Windows Phone

How to: Send and Receive Raw Notifications for Windows Phone

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)