Receiving Push Notifications for Windows Phone

To use the Microsoft Push Notification Service, you must set up your Windows Phone application to receive push notifications from the Microsoft Push Notification Service. To see sample code that implements receiving 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.

To receive push notifications, your client Windows Phone application must:

• Adhere to the requirements listed in the “Push Notifications Applications section” in the Application Certification Requirements for Windows Phone and in section 2.9 of Application Policies.

• Open a push channel if it does not exist, or connect to an existing push channel. A push channel may exist if your application created it in a previous instance of the application. A push channel persists after an application exits if it has been bound to Tile or toast notifications so that these notifications can still be received even though the application is not running.

• If you want to receive toast notifications, you should call the BindToShellToast() method to bind the channel to toast notifications.

• If you want to receive Tile notifications, you bind the channel to Tile notifications by calling the BindToShellTile() method to access local resources on the device or the BindToShellTile(Collection<Uri>) method to access remote resources. To access remote resources, you must provide a collection of allowed domains from which to access remote images. Each URI in the collection is limited to 256 characters.

• Register for the events that you want to receive. All applications should register for the ChannelUriUpdated event in case the push notification URI changes. Even if you already have a channel opened, you should register for the ChannelUriUpdated event in case the URI changes.

  All applications should register for the ErrorOccurred event to handle any errors.

  Applications that use raw notifications must implement the HttpNotificationReceived event to receive the raw data from the notification.

  Toast notifications are ignored if your application is already running, unless you register for the ShellToastNotificationReceived event. Your application can then decide how it wants to respond to the toast notification.

• Each time your application starts, you should pass the URI from your push channel to the web service that sends out the push notifications. It is also recommended that you pass the device ID to your web service so that the web service can track to which devices the URIs are assigned. If a URI changes, then the web service can replace the old URI for that device ID. Windows Phone does not provide a framework to do this, since in most scenarios applications and web services already have their own protocols that they use to communicate with each other.

  Best practices for communicating with your web service include:

  • The application should authenticate with its corresponding web service.

  • The application should encrypt its notification channel URI before sending the URI to its corresponding web service.

  • If your web service will be using notifications properties that do not exist in Windows Phone OS 7.0 – the Parameter property for toast notifications and BackTitle, BackBackgroundImage, BackContent or Tile ID properties for Tile notifications – then you should pass the OS version information to your web service so that the web service can correctly downgrade the notifications for Windows Phone OS 7.0 clients.

  • The web service should validate the notification channel URI received from its corresponding application and store it in a secure manner.

  • When a session is initiated from the application, the notification channel URI should always be sent to its corresponding web service.

  • The web service should have a status code that it can send to its corresponding application that will trigger the application to create a new notification channel URI.

• Register for the ConnectionStatusChanged event. By monitoring the state of the connection to the Microsoft Push Notification Service, you can degrade notification functionality gracefully.

• If the user turns off notifications by changing the setting in your application, as described in section 2.9 of Application Policies, you should be sure to use the Close() method to close the push channel.

• Handle any exceptions that may occur. See the following table for a list of possible exceptions.