Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Guidelines for raw notifications

Applies to Windows and Windows Phone

A raw notification is a type of push notification without any associated UI, unlike the other three kinds of push notifications: toasts, tiles, and badges. As with other push notifications, Windows Push Notification Services (WNS) delivers raw notifications from your cloud service to your app. These guidelines describe how to create effective raw push notifications.

Should my app use raw notifications?

You can use raw notifications for a variety of purposes, including to trigger your app to run a background task if the user has given the app permission to do so. Raw notifications are also an excellent way to be informed when there's data available for your app to download from its cloud service. Your app could:

  • Use the raw notification as a trigger to initiate a file download. For example, if a user purchases an e-book online, send a raw notification to the user's reading app to trigger the download of the new book.
  • Use the raw notification to notify a communication app that there is an incoming instant message or phone call. The communication app can then establish the connection and use a local toast notification to get the user's attention.
  • Use the raw notification to coordinate synchronization actions between the client and the cloud service, such as triggering the sync of the most recently read page of a book in a reader app.

By using Windows Push Notification Services (WNS) to communicate with your app, you can avoid the processing overhead of creating persistent socket connections, sending HTTP GET messages, and other service-to-app connections.

For more info, see the Raw notification overview.

Dos and don'ts

  • Transmit the smallest amount of information in the raw notification that you can. Note that WNS doesn't allow raw notifications to send more than 5 KB of data.
  • Use the notification to indicate that more information is available for the app to download from its cloud service, rather than including that information in the notification.
  • Encode any binary data in the notification as base64 before it is included in a raw notification. This guarantees that the content will not be encoded incorrectly in transit and can be retrieved successfully by the client.
  • Choose the lowest frequency of notifications that still delivers a great user experience.
  • Request a channel each time the app launches. Channel URLs can expire and are not guaranteed to remain the same each time you request one. If the returned channel URL is different than the URL that you had been using, update your reference in your app server.
  • Validate that the channel URL is from WNS. Never attempt to push a notification to a service that isn't WNS. Ensure that your channel URLs use the "windows.com" domain.
  • Always secure your channel registration callback to your app server. When your app receives its channel URL and sends it to your app server, it should send that information securely. Authenticate and encrypt the mechanism used to receive and send channel URLs.
  • Reuse your access token. Because your access token can be used to send multiple notifications, your server should cache the access token so that it doesn't have to reauthenticate each time it wants to send a notification. If the token has expired, your app server will receive an error. Authenticate your app server and retry the notification.
  • Don't use raw notifications to stream information to an app by including small amounts of info in serial notifications. Raw notifications should be sent only in response to events that are triggered on the cloud service.
  • Don't send raw notifications from a cloud service just to keep a background task running. This is an abuse of the user's battery life. A raw notification must communicate useful information to the app.
  • Don't send raw notifications at a rate that causes the associated background task to exceed its resource quota. For more information, see Guidelines for background tasks.
  • Don't use WNS to send critical notifications. Although WNS is reliable, the delivery of notifications isn't guaranteed.
  • Don't use notifications for ads or spam. WNS reserves the right to protect its users and, if an app's use of notifications is deemed inappropriate, the service can block the app from using notifications. If users report that an app is exhibiting malicious intent, that app may be subjected to Windows Store removal policies.
  • Don't include zero-sized payload content in a raw notification. Raw notifications without a payload are dropped by WNS and won't be delivered to your app.
  • Don't send confidential or sensitive data through raw notifications.
  • Don't share your Package Security Identifier (PKSID) and secret key with anyone. Store these credentials on your app server in a secure manner. Routinely generate a new secret key. If your secret key has been compromised, immediately generate a new one.

Additional usage guidance

Before using background tasks triggered by raw notifications in your app, consider the other available methods of communication. A user must explicitly give your app permission to run background tasks and only seven apps can have this permission at once. By using other communication mechanisms in your app, such as standard push notifications or toast updates, your app won't rely on a user allowing it to run background tasks.

Alternatives to background tasks include:

  • To get the user's attention, send a toast push notification.
  • To update a tile, use a tile push notification.

Related topics

For developers (HTML)
RawNotification
Raw notification overview
Quickstart: Creating and registering a raw notification background task
Quickstart: Intercepting push notifications for running apps
For developers (XAML)
RawNotification
Raw notification overview
Quickstart: Creating and registering a raw notification notification background task
Quickstart: Intercepting push notifications for running apps
Sample
Raw notifications sample

 

 

Show:
© 2014 Microsoft