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

Article
05/20/2016

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

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

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

Adhere to the requirements listed in the “Push Notifications Apps section” in the App certification requirements for Windows Phone and in section 2.9 of App policies for Windows Phone.
Open a push channel if it does not exist, or connect to an existing push channel. A push channel may exist if your app created it in a previous instance of the app. A push channel only persists after an app exits if it has been bound to Tile or toast notifications so that these notifications can still be received even though the app is not running.
When using raw notifications, the push channel is removed when the app is not running. Apps that require a push channel that persists, such as VoIP apps, should bind the push channel to a ShellTile or ShellToast by calling BindToShellTile()()() or BindToShellToast()()(). For more information on creating VoIP apps, see VoIP apps for Windows Phone 8.
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<(Of <(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 apps 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 apps should register for the ErrorOccurred event to handle any errors.

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

Toast notifications are ignored if your app is already running, unless you register for the ShellToastNotificationReceived event. Your app can then decide how it wants to respond to the toast notification.
Each time your app starts, you should pass the URI from your push channel to the cloud service that sends out the push notifications. It is also recommended that you pass the device ID to your cloud service so that the cloud service can track to which devices the URIs are assigned. If a URI changes, then the cloud service can replace the old URI for that device ID. Windows Phone does not provide a framework to do this, since in most scenarios apps and cloud services already have their own protocols that they use to communicate with each other.

Best practices for communicating with your cloud service include:
- The app should authenticate with its corresponding cloud service.
- The app should encrypt its notification channel URI before sending the URI to its corresponding cloud service.
- If your cloud service will be using notifications properties that do not exist in Windows Phone OS 7.0 then you should pass the OS version information to your cloud service so that the cloud service can correctly downgrade the notifications for Windows Phone OS 7.0 clients.
- The cloud service should validate the notification channel URI received from its corresponding app and store it in a secure manner.
- When a session is initiated from the app, the notification channel URI should always be sent to its corresponding cloud service.
- The cloud service should have a status code that it can send to its corresponding app that will trigger the app 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 app, as described in section 2.9 of App policies for Windows Phone, you should be sure to use the Close()()() method to close the push channel.
Handle any exceptions that may occur. See the following section for a list of possible exceptions.

Push notification errors and exceptions

The following errors can be returned via the ErrorOccurred event handler callback of the HttpNotificationChannel object.

Error	Description
PushErrorTypeChannelOpenFailed	The channel does not exist, but could not be opened. Try opening the channel again.
PushErrorTypeMessageBadContent	A remote URL was specified in the tile notification payload and one of the following conditions was not met: 1) It was not http://, 2) the host name exceeded 256 characters, 3) the URL exceeded 2055 characters, 4) the domain was not specified in the allowed domains collection. The value of a <Param> tag in a toast notification payload exceeded the limit of 256 characters.
PushErrorTypeNotificationRateTooHigh	The rate of incoming notifications is currently too high. Slow the rate of incoming notifications to avoid dropped messages.
PushErrorTypePayloadFormatInvalid	The XML payload contains invalid or improperly formatted XML or the notification type specified in the header does not match the payload type used. The channel has been closed. Check your XML payload for errors and reopen the channel to obtain a new URI.
PushErrorTypePowerLevelChanged	This has been deprecated because push client no longer takes any action based on any power states.
PushErrorTypeUnknown	An internal error has occurred and could not be recovered. A device reboot may be necessary.

The following errors can return an InvalidOperationException for an HttpNotificationChannel object API call.

Error	Description
PushNotificationTileUriBindFailed	A remote URL was specified in the allowed domains collection and one of the following conditions was not met: 1) It was not http://, 2) the host name exceeded 256 characters, 3) the URL exceeded 2055 characters.
PushNotificationChannelBindFailed	BindToShellTile or BindToShellToast failed. Try binding again.
PushNotificationChannelBindingExists	BindToShellTile or BindToShellToast failed because it is already bound to the channel. Check the IsShellToastBound or IsShellTileBound properties or UnbindToShellToast or UnbindToShellTile before binding again.
PushNotificationChannelExists	Open failed because the channel was already open. You can find an open channel by calling the Find method.
PushNotificationChannelNotOpened	The channel has not yet been opened. You must open the channel before trying this operation.
PushNotificationChannelOpenFailed	The channel does not exist, but could not be opened. Try opening the channel again.
PushNotificationChannelQuotaExceeded	The maximum number of channels has already been opened on this device. A channel must be removed before a new one can be opened.
PushNotificationChannelServerUnavailable	The push client service is temporarily unavailable. Try the operation again later.
ShellInvalidInterval	The specified interval is not allowed. Check the documentation for allowed intervals.
ShellInvalidRemoteImageUri	The specified remote image URI is invalid. Only well-formed HTTP URIs to JPG or PNG files are allowed. HTTPS and other URI types are not allowed.
ShellInvalidUri	The specified local image URI is invalid. Only well-formed local URIs to JPG or PNG files are allowed.

Detecting if push notifications will be disabled due to Battery Saver

Warning

The API that enables this feature is only available on devices with Windows Phone 8 Update 3 (OS version number 8.0.10492) or later. You must check the device OS version before attempting to use this feature.

If the user has enabled the Battery Saver feature on their phone and the battery drops below the minimum power threshold making Battery Saver active, the receipt of push notifications is disabled in order to conserve power. If your app depends heavily on push notifications, you may want to detect when the Battery Saver is enabled and alert the user that push notifications will not be received while Battery Saver is active.

To detect when Battery Saver is enabled you must check the PowerManager.PowerSavingModeEnabled property. Because this property is only available for devices running Windows Phone 8 Update 3, you must access this property via reflection after checking the device OS version. The following example shows you how to detect if Battery Saver is currently enabled.

using Windows.Phone.System.Power;

public void CheckBatterySaverState()
{
    // The minimum phone version that supports the PowerSavingModeEnabled property
    Version TargetVersion = new Version(8, 0, 10492);

    if (Environment.OSVersion.Version >= TargetVersion) 
    {
        // Use reflection to get the PowerSavingModeEnabled value
        bool powerSaveOn = (bool)
            typeof(PowerManager).GetProperty("PowerSavingModeEnabled").GetValue(null, null);

        if (powerSaveOn)
        {
            MessageBox.Show("Battery Saver enabled. This app won’t receive notifications when Battery Saver is active.");
        }
    }
}

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

Push notification errors and exceptions

Detecting if push notifications will be disabled due to Battery Saver

See Also

Other Resources

Additional resources