Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 290 lines (224 sloc) 13.371 kB
1afbd31 @tjanczuk Initial commit
authored
1 wns
2 ===
3
91b3418 @tjanczuk Update master
authored
4 Send push notifications from a node.js application to a Windows 8 device using [Windows Notification Services](http://msdn.microsoft.com/en-us/library/windows/apps/hh913756.aspx).
682f3d3 @tjanczuk update readme
authored
5
6 This module helps you take care of the interaction #5 on the diagram below:
7
8 <img src="http://i.msdn.microsoft.com/dynimg/IC554245.png"/>
9
10 ## What you need
11
91b3418 @tjanczuk Update master
authored
12 * Register your cloud service (web application) at https://manage.dev.live.com/build. Your application will be assigned a Package Security Identifier (SID) and Client Secret. These allow your web application to be authenticated to the Windows Notificaton Service.
682f3d3 @tjanczuk update readme
authored
13 * A channel URL to send notifications to. This is normally created from within your Windows 8 application running on a particular device and securely passed to your web application. The channel URL uniquely identifies the instance of an application running on a particular device.
14
15 ## Your first notification
16
17 Install ```wns``` module with
18
19 ```
20 npm install wns
21 ```
22
23 Then send a notification to your Windows 8 application with
24
7950c11 @tjanczuk Update README.md
authored
25 ```javascript
682f3d3 @tjanczuk update readme
authored
26 var wns = require('wns');
27
7950c11 @tjanczuk Update README.md
authored
28 var channelUrl = '{url to your application notification channel}';
682f3d3 @tjanczuk update readme
authored
29 var options = {
30 client_id: '{your Package Security Identifier}',
31 client_secret: '{your Client Secret}'
32 };
33
34 wns.sendTileSquareBlock(channelUrl, 'Yes!', 'It worked!', options, function (error, result) {
35 if (error)
36 console.error(error);
37 else
38 console.log(result);
39 });
40 ```
41
42 ## Notification types
43
44 Windows Notification Service supports [tile](http://msdn.microsoft.com/en-us/library/windows/apps/hh761491.aspx), [toast](http://msdn.microsoft.com/en-us/library/windows/apps/hh761494.aspx) and [badge](http://msdn.microsoft.com/en-us/library/windows/apps/br212849.aspx) notification types. The ```wns``` module offers methods to send each type of notification.
45
46 ### Tile and toast notifications
47
48 For tile notifications, use one of the following methods:
49
50 * sendTileSquareBlock
51 * sendTileSquareText01
52 * sendTileSquareText02
53 * sendTileSquareText03
54 * sendTileSquareText04
55 * sendTileWideText01
56 * sendTileWideText02
57 * sendTileWideText03
58 * sendTileWideText04
59 * sendTileWideText05
60 * sendTileWideText06
61 * sendTileWideText07
62 * sendTileWideText08
63 * sendTileWideText09
64 * sendTileWideText10
65 * sendTileWideText11
66 * sendTileSquareImage
67 * sendTileSquarePeekImageAndText01
68 * sendTileSquarePeekImageAndText02
69 * sendTileSquarePeekImageAndText03
70 * sendTileSquarePeekImageAndText04
71 * sendTileWideImage
72 * sendTileWideImageCollection
73 * sendTileWideImageAndText01
74 * sendTileWideImageAndText02
75 * sendTileWideBlockAndText01
76 * sendTileWideBlockAndText02
77 * sendTileWideSmallImageAndText01
78 * sendTileWideSmallImageAndText02
79 * sendTileWideSmallImageAndText03
80 * sendTileWideSmallImageAndText04
81 * sendTileWideSmallImageAndText05
82 * sendTileWidePeekImageCollection01
83 * sendTileWidePeekImageCollection02
84 * sendTileWidePeekImageCollection03
85 * sendTileWidePeekImageCollection04
86 * sendTileWidePeekImageCollection05
87 * sendTileWidePeekImageCollection06
88 * sendTileWidePeekImageAndText01
89 * sendTileWidePeekImageAndText02
90 * sendTileWidePeekImage01
91 * sendTileWidePeekImage02
92 * sendTileWidePeekImage03
93 * sendTileWidePeekImage04
94 * sendTileWidePeekImage05
95 * sendTileWidePeekImage06
96
97 For toast notifications, use one of the following methods:
98
99 * sendToastText01
100 * sendToastText02
101 * sendToastText03
102 * sendToastText04
103 * sendToastImageAndText01
104 * sendToastImageAndText02
105 * sendToastImageAndText03
106 * sendToastImageAndText04
107
108 Each of the methods that send tile and toast notifications have two altenative parameter signatures:
109
110 ```
111 sendXYZ(channel, payload, [options], [callback])
112 sendXYZ(channel, string1, string2, ..., [options], [callback])
113 ```
114
115 In both cases the meaning of ```channel```, ```options```, and ```callback``` is the same:
116
117 * ```channel``` [required] - the notification channel URL of the target instance of a Windows 8 application.
118 * ```options``` [optional] - allows specifying web application credentials to authenticate the web application to Windows Notification Service. If this parameter is not specified, the ```WNS_CLIENT_ID``` environment variable must be set to the Package Security Identifier (SID), and the ```WNS_CLIENT_SECRET``` environment variable must be set to the Client Secret of the web application.
91b3418 @tjanczuk Update master
authored
119 * ```client_id``` [optional] - Package Security Identifier (SID) or the web application. If absent, the value must be provided through ```WNS_CLIENT_ID``` environment variable.
120 * ```client_secret``` [optional] - Client Secret of the web application. If absent, the value must be provided through the ```WNS_CLIENT_SECRET``` environment variable.
121 * ```accessToken``` [optional] - OAuth access token to be used to send notifications. This is normally issued by Windows Notification Service during one of the prior calls to send a notification and passed to the applicaton through the ```callback``` parameter.
122 * ```headers``` [optional] - any additional HTTP request headers to include in the request sent to Windows Notification Service. For a list of available HTTP request headers see [here](http://msdn.microsoft.com/en-us/library/windows/apps/hh465435.aspx).
825c56b @tjanczuk Update README.md
authored
123 * ```launch``` [optional; toast notifications only] - application specific string payload that will be delievered to the client device along with the toast notification
124 * ```duration``` [optional; toast notifications only] - duration the toast notification will be shown; valid values are ```long``` and ```short```
682f3d3 @tjanczuk update readme
authored
125 * ```callback``` [optional] - a callback function that will be invoked with two parameters: (error, result), where only one is present at any time. The ```error``` parameter is an instance of ```Error``` while ```result``` is a regular object. Both contain the following members:
91b3418 @tjanczuk Update master
authored
126 * ```statusCode``` [optional] - the HTTP response status code from Windows Notification Service (for definitions see [here](http://msdn.microsoft.com/en-us/library/windows/apps/hh465435.aspx#send_notification_response)).
127 * ```headers``` [optional] - the HTTP response headers (for WNS specific HTTP response headers see [here](http://msdn.microsoft.com/en-us/library/windows/apps/hh465435.aspx#send_notification_response)).
128 * ```innerError``` [optional] - in case of an error this may contain more information about the condition.
129 * ```newAccessToken``` [optional] - if a new OAuth access token had been obtained in the course of processing the request, it will be provided here. Subsequent calls to ```sendXYZ``` functions should specify this value in the ```options.accessToken``` field.
682f3d3 @tjanczuk update readme
authored
130
131 The two ```sendXYZ``` method overrides differ in how notification parametrs are specified. Each kind of tile or toast notification contains a specific number of images and text fields. Each image is specified with two strings: its URL and its alternative text. Each text field is specified with just one string.
132
133 The overload that accepts a sequence of ```string1, string2, ...``` parameters requires each of these parameters to be a string corresponding to an image or text field definition. The order of these fields must match the document order of a specific field in the [tile](http://msdn.microsoft.com/en-us/library/windows/apps/hh761491.aspx) or [toast](http://msdn.microsoft.com/en-us/library/windows/apps/hh761494.aspx) notification schema corresponding to the method name (e.g. ```sendTileSquarePeekImageAndText01``` requires a total of 6 parameters in that order: 1 to specify the image URL, 1 to specify the image alt text, and 4 simple text parameters).
134
135 The overload that accepts the ```payload``` parameter requires that ```payload``` is an object. Fields of the object allow specification of image and text parameters using the following naming convention:
136
137 * ```image{N}src``` specifies the URL of the N-th image in document order, starting from 1
138 * ```image{N}alt``` specifies the alt text of the N-th image in document order, starting from 1
139 * ```text{N}``` specifies the value of the N-th text field in document order, starting from 1
140 * any parameters that are missing are assumed to be empty strings
141 * any extra parameters not required by a particular tile or toast template are ignored
142
143 For example:
144
7950c11 @tjanczuk Update README.md
authored
145 ```javascript
682f3d3 @tjanczuk update readme
authored
146 var channel = '{channel_url}';
147 var currentAccessToken;
148
149 wns.sendTileSquarePeekImageAndText01(
150 channel,
151 {
152 image1src: 'http://foobar.com/dog.jpg',
153 image1alt: 'A dog',
154 text1: 'This is a dog',
155 text2: 'The dog is nice',
156 text3: 'The dog bites',
157 text4: 'Beware of dog'
158 },
159 {
160 client_id: '{your Package Security Identifier}',
161 client_secret: '{your Client Secret}',
162 accessToken: currentAccessToken
91b3418 @tjanczuk Update master
authored
163 },
164 function (error, result) {
682f3d3 @tjanczuk update readme
authored
165 currentAccessToken = error ? error.newAccessToken : result.newAccessToken;
166 });
167 ```
168
c3e8716 @tjanczuk update readme
authored
169 ### Sending multiple tile or toast notifications at once
170
171 You can send multiple toast or tile notifications in a single update to the client. This feature is useful since the client device may then choose one the tile or toast formats that suites its local configuration best. For example, you may send two semantically equivalent tiles, one square and the other wide. The client UI will decide which one to show based on its configuration.
172
173 To send multiple toasts or tiles in a single update use one of these methods:
174
175 ```javascript
176 wns.sendTile(channel, tile1, tile2, ..., [options], [callback])
177 wns.sendToast(channel, toast1, toast2, ..., [options], [callback])
178 ```
179
180 The meaning and behavior or `channel`, `options`, and `callback` is the same as for the `wns.sendXYZ` APIs which send a single toast or tile.
181
182 The `tile1`, `tile2`, etc. parameters describe the tile or toast binding which defines its appearance. These are JavaScript objects constructed the same way as you would construct them for use with `wns.sendXYZ` methods, but contain one extra property named `type`. The `type` property is a string name of the tile or toast template, e.g. `TileSquareBlock`. For a complete list of available tile and toast template names see [tile](http://msdn.microsoft.com/en-us/library/windows/apps/hh761491.aspx) and [toast](http://msdn.microsoft.com/en-us/library/windows/apps/hh761494.aspx) documentation.
183
184 For example:
185
186 ```javascript
187 var channel = '{channel_url}';
188
189 wns.sendTile(
190 channel,
191 {
192 type: 'TileSquareText04',
193 text1: 'Hello'
194 },
195 {
196 type: 'TileWideText09',
197 text1: 'Hello',
198 text2: 'How are you?'
199 },
200 {
201 client_id: '{your Package Security Identifier}',
202 client_secret: '{your Client Secret}'
203 },
204 function (error, result) {
205 // ...
206 });
207 ```
208
209 The code above sends an update with two tile definitions: TileSquareText04 and TileWideText09. The client agent will choose the tile update to show.
210
211 ### Selecting language and other tile or toast parameters
212
213 You can add several parameters to tile and toast notifications by adding properties to the object that defines the tile or toast. For example, to indicate the target language is German, you can use the `lang` property as follows:
214
215 ```javascript
216 wns.sendTileSquareText04(
217 channel,
218 {
219 text1: 'Herzlich Willkommen',
220 lang: 'de'
221 },
222 {
223 client_id: '{your Package Security Identifier}',
224 client_secret: '{your Client Secret}'
225 },
226 function (error, result) {
227 // ...
228 });
229 ```
230
231 You can use this method to specify `lang`, `fallback`, `baseUri`, `branding`, and `addImageQuery` parameters of a toast or tile as specified [here](http://msdn.microsoft.com/en-us/library/windows/apps/br230843.aspx).
232
682f3d3 @tjanczuk update readme
authored
233 ### Badge notifications
234
91b3418 @tjanczuk Update master
authored
235 To send a badge notification, use this method:
682f3d3 @tjanczuk update readme
authored
236
7950c11 @tjanczuk Update README.md
authored
237 ```javascript
682f3d3 @tjanczuk update readme
authored
238 wns.sendBadge(channel, value, [options], [callback])
239 ```
240
241 The meaning and behavior of ```channel```, ```options```, and ```callback``` is the same as for tile and toast notifications.
242
91b3418 @tjanczuk Update master
authored
243 The ```value``` can be either a simple string or number, in which case it can assume values specified [here](http://msdn.microsoft.com/en-us/library/windows/apps/br212849.aspx), or it can be an object with 2 properties:
682f3d3 @tjanczuk update readme
authored
244
245 * ```value``` [required] - one of the values specified [here](http://msdn.microsoft.com/en-us/library/windows/apps/br212849.aspx).
246 * ```version``` [optional] - badge schema version (by default 1).
247
248 For example:
249
7950c11 @tjanczuk Update README.md
authored
250 ```javascript
682f3d3 @tjanczuk update readme
authored
251 var channel = '{channel_url}';
252 wns.sendBadge(channel, 'alert');
253 ```
254
825c56b @tjanczuk Update README.md
authored
255 ### Raw notifications
256
257 To send a raw notification, use this method:
258
259 ```javascript
260 wns.sendRaw(channel, value, [options], [callback])
261 ```
262
263 The meaning and behavior of ```channel```, ```options```, and ```callback``` is the same as for tile and toast notifications.
264
265 The ```value``` is an application specific string that will be delivered to the client unchanged.
266
267 For example:
268
269 ```javascript
270 var channel = '{channel_url}';
271 wns.sendRaw(channel, JSON.stringify({ foo: 1, bar: 2 }));
272 ```
273
682f3d3 @tjanczuk update readme
authored
274 ### Low level notifications
275
276 There is one more method that allows sending pre-formatted notifiction messages that adhere to the tile, toast, or badge schema:
277
7950c11 @tjanczuk Update README.md
authored
278 ```javascript
682f3d3 @tjanczuk update readme
authored
279 wns.send(channel, payload, type, [options], [callback])
280 ```
281
825c56b @tjanczuk Update README.md
authored
282 The caller takes responsibility for providing a pre-formatted string (typically with XML) of the notification as the ```payload``` parameter. The ```type``` parameter specifies the type of the notification as one of the string values specified [here](http://msdn.microsoft.com/en-us/library/windows/apps/hh465435.aspx#pncodes_x_wns_type).
f432bf8 @tjanczuk Update master
authored
283
001001e @tjanczuk Update master
authored
284 ## Running tests
f432bf8 @tjanczuk Update master
authored
285
001001e @tjanczuk Update master
authored
286 Tests are using mocha and nock which are listed as dev dependencies. To run tests invoke mocha from the root of the repository:
f432bf8 @tjanczuk Update master
authored
287
001001e @tjanczuk Update master
authored
288 ```
289 mocha
290 ```
Something went wrong with that request. Please try again.