This topic describes best practices for using push notifications and lists any requirements your app needs to meet to be accepted in the Windows Store.
Guidelines
- Follow the overall tile and toast notification guidelines. Whether a tile or toast notification is generated locally or through the cloud, it should respect the same user guidelines. For more information, see these topics:
- Register your app in the Dashboard. You cannot use Windows Push Notification Services (WNS) unless your app is registered with the Dashboard. Your app server has to use the specific credentials provided by the Dashboard to authenticate and send notifications.
- Respect your user's battery life. Your users can receive notifications at any time, even when their device is in a low power state. The more notifications that you send, the more resources it will require and the more frequently you will wake up the device. Keep this in mind when you determine the frequency of your notifications—increasing the frequency of your notifications does not always increase the value of your app. For example, if your tile content is updated too frequently, some of your updates will never be seen by the user. Developers should choose the lowest frequency of notifications that will still achieve a great user experience.
- Do not use push notifications for spam or with malicious intent. If an app sends overly frequent notifications simply to be obnoxious or monopolize bandwidth, or sends notifications that are considered spam, WNS reserves the right to protect its users. WNS can block selected apps from using push notifications. In addition, if users report that an app is exhibiting malicious intent, that app could be subjected to Windows Store removal policies.
- Implement channel renewal. Channel URLs can expire and are not guaranteed to remain the same each time you request one. Therefore, your app should request a channel each time the app launches. If the returned channel URL is different than the URL that you had been using, update your reference in your app server.
- Reuse your access token. Your access token can be used to send multiple notifications. Therefore, your server should cache the access token so that it does not need to reauthenticate each time it wants to send a notification. If the token has expired, your app server will receive an error and you should authenticate your app server and retry the notification.
- Be aware that WNS has no delivery guarantees. Although WNS maintains high levels of availability and reliability, ultimately, the delivery of notifications cannot be guaranteed. Your app should not use WNS for critical notifications.
Troubleshooting
Push notification receives a "200 OK" response, but does not display
If WNS returns a "200 OK" response, then it will deliver the notification to the client if the client is online. If you have verified that the client is online but not displaying the notification, walk through these steps:
-
Cause: XML errors in the notification content.
Fix: Verify the basic XML syntax and make sure that your XML is complete and correct. Some common points of failure in the XML content include the following:
- Case sensitivity. Tag names, attribute names, and attribute values are all case sensitive. Be sure that your XML has the correct casing.
- A binding element must be provided for each tile size in a tile notification. If you support wide tiles, you should provide both square and wide template binding elements for each tile you send.
- Text strings should not contain reserved XML characters. For example, you cannot italicize tile or toast strings by including <i> and </i> tags. If you intend to show the literal characters "<i>", they should be properly escaped. For more information on escape characters in XML, see XML Character Entities and XAML.
- The values supplied for the lang attributes must conform to the ITEF BCP 47 specification.
- XML strings sent through push notifications should use the UTF-16 encoding.
- If you include an image element in your XML payload with a non-empty src attribute, you must be sure to include a reference to a valid image or the notification will fail.
For more information, see the Tiles, toast, and badge schemas documentation.
-
Cause: Improper use of push notification API parameters
Fix: See the API documentation in the Windows.Networking.PushNotifications namespace for specifics.
-
Cause: Header type does not match notification content. If the X-WNS-Type header is not set to a value—tile, badge, or toast—that corresponds to the notification template specified in the payload, the notification will not be displayed. This mismatch will cause an error on the client and the notification will be dropped.
Fix: Refer to Push notification service request and response headers to ensure that your app server is using the correct value for the X-WNS-Type header.
-
Cause: The time to live (TTL) value, set in the X-WNS-TTL header, is too small.
Fix: Provide a larger TTL value, being aware that the value is given in seconds.
If you still do not see your notification displayed after addressing the items in the previous steps, see the troubleshooting steps for local notifications in Guidelines and checklist for tiles for further suggestions.
Push notification returns a code other than "200 OK"
If WNS doesn't return "200 OK", your notification will not be delivered to the client. If the return code is in the 400s, then you, as a developer, should be able to fix the issue. For information on the meaning of specific codes, see WNS response code reference.
- Notification request returns "400 Bad Request"
- Notification request returns "401 Unauthorized"
- Notification request returns "401 Unauthorized", token is expired
- Notification request returns "403 Forbidden"
- Notification request returns "404 Not Found"
- Notification request returns "406 Not Acceptable"
- Notification request returns "410 Gone"
Notification request returns "400 Bad Request"
Cause: The use of one or more WNS headers could be incorrect or the HTTP request was invalid.
Fix: Refer to Push notification service request and response headers to ensure that your app server is using all custom headers as described.
Notification request returns "401 Unauthorized"
Cause: Your app server must use the correct Package Security Identifier (Package SID) and secret given to you when registered your app. If you have recently changed your secret in the Windows Store Dashboard, you will also need to update your app server. For more information, see the Push notifications overview.
Fix: Visit the Windows StoreDashboard to verify your Package SID and secret.
Notification request returns "401 Unauthorized", token is expired
Cause: An access token has a finite lifetime. If you send a notification with an expired access token, your app server's credentials are invalid and the notification cannot be sent.
Fix: Request a new access token from WNS by authenticating with WNS using your Package Security Identifier (Package SID) and secret. For more information, see the Push notifications overview.
Notification request returns "403 Forbidden"
Cause: This error occurs when the access token that you presented does not match the credentials required to send notifications to the corresponding channel URL. Every app must be registered with the Windows Store to receive credentials for its app server. For each app, only the credentials provided by the Windows Store can be used to send notifications to that app and they can be used only for that particular app.
Fix: Log into the Windows Store Dashboard with your developer account. Select your app and click "Advanced Features" -> "Manage your cloud service settings". Select "Identifying your app" to read instructions on updating your app manifest to match your cloud service credentials.
Notification request returns "404 Not Found"
Cause: This error typically means that the channel URL is not formed correctly. The channel URL must never be tampered with or modified when you send a notification to WNS. The channel URL should always be treated as an opaque string—you never need to examine or even know its content.
Fix: Verify that your code is not modifying the channel URL either by changing one or more of its characters or changing its encoding.
Notification request returns "406 Not Acceptable"
Cause: WNS has protective policies in place to prevent malicious apps from negatively impacting the service for other users and developers. An excessive number of notifications in too short a time period can result in WNS explicitly dropping notifications.
Fix: Review your notification frequency to see if it can be decreased or optimized to produce a better user experience.
Notification request returns "410 Gone"
Cause: The channel URL has expired. No further notifications can be sent until your app runs and requests a new channel URL.
Fix: Your Windows Store app should always request a channel URL when it is launched. The channel URL that it is assigned is not guaranteed to remain the same. If the URL has changed, the client should update the information on its cloud server. For more information, see How to manage channel expiration and renewal.
Errors when attempting to create a push notification channel
- Creating a notification channel results in an ERROR_NO_NETWORK error
- Creating a notification channel results in an WPN_E_CLOUD_INCAPABLE error
- Creating a notification channel results in an WPN_E_INVALID_APP error
Creating a notification channel results in an ERROR_NO_NETWORK error
Cause: WNS requires an Internet connection to create a notification channel.
Fix: Check your Internet connectivity.
Creating a notification channel results in an WPN_E_CLOUD_INCAPABLE error
Cause: Your app has not declared the Internet capability in its app manifest (package.appxmanifest).
Fix: Ensure that your app manifest has declared Internet capability. In the Microsoft Visual Studio Express 2012 for Windows 8 manifest editor, you will find this option under the Capabilities tab as Internet (Client). For more information, see Capabilities.
Creating a notification channel results in an WPN_E_INVALID_APP error
Cause: Your app must use a valid package name. If you have not received one yet, you can get it through the Windows Store portal under "Advanced Features".
Fix: For details on retrieving a Package Security Identifier (PKSID) for your Windows Store app, see How to authenticate with the Windows Push Notification Service (WNS).
Reporting an issue
If you have tried the solutions suggested in this topic, plus those in the troubleshooting sections of Guidelines and checklist for tiles and Guidelines and checklist for toast notifications and have not resolved your issue, post the issue on the Microsoft forums.
In addition to a description of the problem, you may be asked to provide your channel URL and an example of the response you received from WNS, including both the HTTP error codes and HTTP headers. There are specific headers that your app server should be logging when reporting an issue. For more information, see Push notification service request and response headers.
Checklist
For general Windows Store requirements, see Certification requirements for Windows apps.
Security Considerations
- Do not send confidential or sensitive data through push notifications. Push notifications are not intended to carry highly sensitive or confidential information. For example, a bank account number or password should never be sent in a notification.
- 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. We recommend that the mechanism used to do so be authenticated and encrypted.
- Validate that the channel URL is from WNS. Never attempt to push a notification to a service that is not WNS. Always ensure that your channel URLs use the windows.com domain.
- Keep your app server credentials a secret. Never share your Package Security Identifier (PKSID) and secret key with anyone. Store those credentials on your app server in a secure manner. If you believe that your secret key has been compromised, generate a new key. We recommended that you routinely generate a new secret key to present villains with a moving target.
Related topics
Build date: 11/29/2012
