How to request, create, and save a notification channel (HTML)
Note Not using JavaScript? See How to request, create, and save a notification channel (XAML).
You can open a channel Uniform Resource Identifier (URI) over which your app can receive push notifications. You can then send the channel to your server which uses it to send push notifications, and close it when you no longer need it. A channel is a unique address that represents a single user on a single device, for a specific app or secondary tile.
You should request a new channel each time that your app is launched, and update the cloud server when the URI changes. For more details, see Remarks.
Important Notification channels automatically expire after 30 days.
What you need to know
Technologies
- Windows Runtime
Prerequisites
- A working knowledge of tile and notification terms and concepts, as well as XML. This topic also assumes that you know how to create a basic Windows Store app with JavaScript using Windows Runtime APIs.
- Familiarity with push notification and Windows Push Notification Services (WNS) concepts, requirements, and operation. These are discussed in the Windows Push Notification Services (WNS) overview.
Instructions
Step 1: Request a channel URI
This example requests a channel URI. The request is made to the Notification Client Platform, which in turn requests the channel URI from WNS. When the request is complete, the returned value is a PushNotificationChannel object that contains the URI.
var channel;
var pushNotifications = Windows.Networking.PushNotifications;
var channelOperation = pushNotifications.PushNotificationChannelManager.createPushNotificationChannelForApplicationAsync();
return channelOperation.then(function (newChannel) {
channel = newChannel;
// Success. The channel URI is found in newChannel.uri.
},
function (error) {
// Could not create a channel. Retrieve the error through error.number.
}
);
Step 2: Send the channel URI to your server
The channel URI is packaged in an HTTP POST request and sent to the server.
Important You should send this information to your server in a secure manner. You should require the app to authenticate itself with the server when it transmits the channel URI. Encrypt the information and use a secure protocol such as HTTPS.
var serverUrl = "https://www.contoso.com";
var xhr = new WinJS.xhr({
type: "POST",
url: serverUrl,
headers: {"Content-Type": "application/x-www-form-urlencoded"},
data: "channelUri=" + channel.uri
}).then(function (req) {
// Channel URI successfully sent to server. Retrieve the response from req.response.
},
function (req) {
// Could not send channel URI to server. Retrieve the error through req.statusText.
}
);
Remarks
Requesting channels
You should request a new channel each time your app is invoked, by using the following logic:
- Request a channel.
- Compare the new channel with your previous channel. If the channel is the same, you don't need to take any further action. Note that this requires your app to store the channel locally each time the app successfully sends it to your service, so that you have the channel to compare against later.
- If the channel has changed, send the new channel to your web service. Include error handling logic that always sends a new channel in the following cases:
- Your app has never sent a channel to the web service before.
- Your app's last attempt to send the channel to the web service was not successful.
Different calls to the createPushNotificationChannelForApplicationAsync method do not always return a different channel. If the channel has not changed since the last call, your app should conserve effort and Internet traffic by not resending that same channel to your service. An app can have multiple valid channel URIs at the same time. Because each unique channel remains valid until it expires, there is no harm in requesting a new channel because it does not affect the expiration time of any previous channels.
By requesting a new channel each time your app is invoked, you maximize your chances of always having access to a valid channel. This is particularly important if it is vital to your tile or toast scenario that content always be live. If you are concerned that a user might not run your app more than once every 30 days, you can implement a background task to execute your channel request code on a regular basis.
Handling errors in channel requests
The call to the createPushNotificationChannelForApplicationAsync method can fail if the Internet is not available. To handle this, add retry logic to the code shown in step 2. We recommend three attempts with a 10-second delay between each unsuccessful attempt. If all three attempts fail, your app should wait until the next time the user launches it to try again.
Closing channels
Your app can immediately stop the delivery of notifications on all channels by calling the close method. While it will not be common for your app to do so, there might be certain scenarios in which you want to stop all notification delivery to your app. For instance, if your app has the concept of user accounts and a user logs out of that app, it is reasonable to expect that the tile no longer shows that user's personal information. To successfully clear the tile of content and stop the delivery of notifications, you should do the following:
- Stop all tile updates by calling the PushNotificationChannel.close method on any of your notification channels that are delivering tile, toast, badge or raw notifications to a user. Calling the close method ensures that no further notifications for that user can be delivered to the client.
- Clear the contents of the tile by calling the TileUpdater.clear method to remove the previous user's data from the tile.
Related topics
Push and periodic notifications sample
Windows Push Notification Services (WNS) overview
Quickstart: Sending a push notification
How to authenticate with the Windows Push Notification Service (WNS)
How to manage channel expiration and renewal