Compartilhar via

Sending push notifications for Windows Phone 8

  • Artigo

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

After your Windows Phone client app has registered for notifications, you can send notifications to the app. 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 app that can send messages to the Microsoft Push Notification Service. The Microsoft Push Notification Service in Windows Phone is an asynchronous, best-effort service that offers third-party developers a channel to send data to a Windows Phone app from a cloud service in a power-efficient manner. To see sample code that demonstrates how to send push notifications, see How to send and receive toast notifications for Windows Phone 8, How to send and receive Tile notifications for Windows Phone 8, and How to send and receive raw notifications for Windows Phone 8.

Important Note:

We recommend setting up an authenticated web service to send your notifications to the 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 info, see Setting up an authenticated web service to send push notifications for Windows Phone 8.

To send push notifications, your web service or app 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 (toast, Tile, 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 not available on Windows Phone OS 7.0, specifically, the Parameter property for toast notifications and the BackTitle, BackBackgroundImage, BackContent or Tile ID properties for Tile notifications. We recommend that you send the device OS version info at the same time you register the device URI info with your web service.

  • Post the messages to the push notification service.

  • Get the response from the push notification service and respond accordingly.

Note

If you specify that a remote URI is used to update your app's Tile image and the user changes your app's Tile size, Windows Phone begins the process of downloading and updating the Tile image. If Windows Phone was in the process of updating the Tile image to a local resource and a request was made to update the Tile image with a remote URI, your Tile image will show the remote resource rather than the local resource.

This topic contains the following sections.

Custom HTTP headers

Custom HTTP headers can include a notification message ID, batching interval, the type of push notification being sent, and the notification channel URI.

The MessageID is the notification message ID associated with the response. If this header is not added to the POST request, the push notification service omits this header in the response. The header specification is "X-MessageID"":"1*MessageIDValue MessageIDValue = STRING (uuid).

For example: X-MessageID: UUID

The NotificationClass is the batching interval that indicates when the push notification will be sent to the app 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. The header specification is ”X-NotificationClass””:”1*NotificationClassValue NotificationClassValue = DIGIT.

For example: X-NotificationClass:1

The Notification Type is 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 info, see Push notifications for Windows Phone 8. The header specification is “X-WindowsPhone-Target””:”1*NotificationTypeValue NotificationTypeValue = STRING.

For example: X-WindowsPhone-Target:toast

Special characters

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

Character

XML encoding

<

&lt;

>

&gt;

&

&amp;

‘

&apos;

“

&quot;

Tile and toast notification payloads

The following sections describe payload info needed for sending a push notification to a toast or Tile.

Toast notification payloads

For general info about how to structure the toast notification payload using code or XML, as well as for info about how to structure the payload to deep link into your app, see Toasts for Windows Phone 8.

Toast notification payload HTTP headers

Use the following HTTP headers when creating a toast notification:

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

Toast notification batching intervals

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.

Tile notification payloads

For general info about how to structure the Tile notification payload in Windows Phone OS 7.1, as well as for info about how to clear and delete the Tile, see How to create, delete, and update Tiles for Windows Phone OS 7.1. For Windows Phone 8 apps, see the individual Tile template topics for more info on how to structure the Tile notification payload. Flip Tile template for Windows Phone 8, Iconic Tile template for Windows Phone 8, or Cycle Tile template for Windows Phone 8.

Tile notification payload HTTP headers

Use the following HTTP headers when sending a Tile notification.

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

Tile notification batching intervals

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.

Sending push notifications to secondary Tiles

If your app has secondary Tiles, the Id attribute designates which Tile to update. You can omit the Id attribute of the Tile element if updating your app's default Tile.

The following code shows an example of the Id attribute of the Tile element, which should contain the exact navigation URI of the secondary Tile.

string tileMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<wp:Notification xmlns:wp=\"WPNotification\">" +
  "<wp:Tile Id=\"/SecondaryTile.xaml?DefaultTitle=FromTile\">" +
…
  "</wp:Tile> " +
"</wp:Notification>";

Raw Tile notification payload

Use the following HTTP headers when sending a raw Tile notification.

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 app. The following code shows an example.

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

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

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

See Also

Other Resources

Push notifications for Windows Phone 8

Setting up your app to receive push notifications for Windows Phone 8

How to send and receive toast notifications for Windows Phone 8

How to send and receive Tile notifications for Windows Phone 8

How to send and receive raw notifications for Windows Phone 8