Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 190 lines (129 sloc) 9.561 kb
7a92810 @argon Updated the readme
authored
1 #node-apn
2
b520596 @argon BADGE ALL THE THINGS.
authored
3 > A Node.js module for interfacing with the Apple Push Notification service.
4
5 [![NPM][npm-image] ][npm-url]
6
7 [![Build status][ci-image] ][ci-url]
8 [![Code coverage][coverage-image]][coverage-url]
9 [![Codacy][codacy-image]][codacy-url]
10
11 [![dependencies][dependencies-image]][dependencies-url]
12 [![devdependencies][devdependencies-image]][devdependencies-url]
13
14 [![Issue Stats][issuestats-pr-image]][issuestats-url]
15 [![Issue Stats][issuestats-image]][issuestats-url]
16
17 [npm-image]:https://nodei.co/npm/apn.png?downloads=true
18 [npm-url]:https://npmjs.com/package/apn
19 [ci-image]:https://travis-ci.org/argon/node-apn.png?branch=master
20 [ci-url]:https://travis-ci.org/argon/node-apn
21 [coverage-image]:https://coveralls.io/repos/argon/node-apn/badge.svg?branch=master
22 [coverage-url]:https://coveralls.io/r/argon/node-apn
23 [codacy-image]:https://www.codacy.com/project/badge/e7735fbe0db244f3b310657d0dabaa11
24 [codacy-url]:https://www.codacy.com/public/argon/node-apn
25
26 [dependencies-image]:https://david-dm.org/argon/node-apn.png
27 [dependencies-url]:https://david-dm.org/argon/node-apn
28 [devdependencies-image]:https://david-dm.org/argon/node-apn/dev-status.png
29 [devdependencies-url]:https://david-dm.org/argon/node-apn#info=devDependencies
30
31 [issuestats-image]:http://issuestats.com/github/argon/node-apn/badge/issue
32 [issuestats-pr-image]:http://issuestats.com/github/argon/node-apn/badge/pr
33 [issuestats-url]:http://issuestats.com/github/argon/node-apn
7a92810 @argon Updated the readme
authored
34
35 ## Features
36
4476bae @argon Updated Readme to be shorter and more readable.
authored
37 - Fast
38 - Maintains a connection to the server to maximise notification batching and throughput.
39 - Enhanced binary interface support, with error handling
7a92810 @argon Updated the readme
authored
40 - Automatically sends unsent notifications if an error occurs
41 - Feedback service support
4476bae @argon Updated Readme to be shorter and more readable.
authored
42 - Complies with all best practises laid out by Apple
7a92810 @argon Updated the readme
authored
43
44 ## Installation
45
a2fc043 @argon Significant improvements to README
authored
46 Via [npm][]:
7a92810 @argon Updated the readme
authored
47
48 $ npm install apn
49
5530d7d @argon Lots of Doc. Some Notification helper methods.
authored
50 As a submodule of your project (you will also need to install [q][q])
7a92810 @argon Updated the readme
authored
51
a2fc043 @argon Significant improvements to README
authored
52 $ git submodule add http://github.com/argon/node-apn.git apn
53 $ git submodule update --init
7a92810 @argon Updated the readme
authored
54
4476bae @argon Updated Readme to be shorter and more readable.
authored
55 ## Quick Start
56
57 This is intended as a brief introduction, please refer to the documentation in `doc/` for more details.
58
7a92810 @argon Updated the readme
authored
59 ### Load in the module
60
4476bae @argon Updated Readme to be shorter and more readable.
authored
61 var apn = require('apn');
a847bef @keithnlarsen Make the apn library take a cert and a key as a string instead of as …
keithnlarsen authored
62
7a92810 @argon Updated the readme
authored
63 ### Connecting
95dac54 @argon It's not clear that `production` can be overridden
authored
64 Create a new connection to the APN gateway server, passing a dictionary of options to the constructor. If you name your certificate and key files appropriately (`cert.pem` and `key.pem`) then the defaults should be suitable to get you up and running.
7a92810 @argon Updated the readme
authored
65
4476bae @argon Updated Readme to be shorter and more readable.
authored
66 ```javascript
aae3941 @argon Production flag to switch environments, happens automatically when NO…
authored
67 var options = { };
a847bef @keithnlarsen Make the apn library take a cert and a key as a string instead of as …
keithnlarsen authored
68
4476bae @argon Updated Readme to be shorter and more readable.
authored
69 var apnConnection = new apn.Connection(options);
70 ```
e81cf5b @argon Improved doc.
authored
71
95dac54 @argon It's not clear that `production` can be overridden
authored
72 By default, if the environment variable `NODE_ENV=production` is set, the module will connect to the production gateway. Otherwise it will connect to the sandbox. This along with many other settings can be overriden with the options object.
73
74 For more information about configuration options consult the [documentation](doc/connection.markdown).
75
e81cf5b @argon Improved doc.
authored
76 Help with preparing the key and certificate files for connection can be found in the [wiki][certificateWiki]
7a92810 @argon Updated the readme
authored
77
78 ### Sending a notification
5530d7d @argon Lots of Doc. Some Notification helper methods.
authored
79 To send a notification first create a `Device` object. Pass it the device token as either a hexadecimal string, or alternatively as a `Buffer` object containing the token in binary form.
7a92810 @argon Updated the readme
authored
80
4476bae @argon Updated Readme to be shorter and more readable.
authored
81 var myDevice = new apn.Device(token);
7a92810 @argon Updated the readme
authored
82
e81cf5b @argon Improved doc.
authored
83 Next, create a notification object, set the relevant parameters (See the [payload documentation][pl] for more details.) and use the `pushNotification` method on the connection to send it.
7a92810 @argon Updated the readme
authored
84
4476bae @argon Updated Readme to be shorter and more readable.
authored
85 var note = new apn.Notification();
7a92810 @argon Updated the readme
authored
86
18a5259 @argon Readme.md
authored
87 note.expiry = Math.floor(Date.now() / 1000) + 3600; // Expires 1 hour from now.
7a92810 @argon Updated the readme
authored
88 note.badge = 3;
89 note.sound = "ping.aiff";
72df805 @argon Ensure `Notification#trim` cleanly trims Unicode characters
authored
90 note.alert = "\uD83D\uDCE7 \u2709 You have a new message";
7a92810 @argon Updated the readme
authored
91 note.payload = {'messageFrom': 'Caroline'};
92
4476bae @argon Updated Readme to be shorter and more readable.
authored
93 apnConnection.pushNotification(note, myDevice);
5530d7d @argon Lots of Doc. Some Notification helper methods.
authored
94
7a92810 @argon Updated the readme
authored
95 The above options will compile the following dictionary to send to the device:
96
72df805 @argon Ensure `Notification#trim` cleanly trims Unicode characters
authored
97 {"messageFrom":"Caroline","aps":{"badge":3,"sound":"ping.aiff","alert":"\uD83D\uDCE7 \u2709 You have a new message"}}
98
7a92810 @argon Updated the readme
authored
99 ### Setting up the feedback service
100
101 Apple recommends checking the feedback service periodically for a list of devices for which there were failed delivery attempts.
102
4476bae @argon Updated Readme to be shorter and more readable.
authored
103 Using the `Feedback` object it is possible to periodically query the server for the list. Many of the options are similar to that of `Connection`.
104
105 Attach a listener to the `feedback` event to receive the output as two arguments, the `time` returned by the server (epoch time) and a `Buffer` object containing the device token - this event will be emitted for each device separately. Alternatively you can enable the `batchFeedback` option and the `feedback` event will provide an array of objects containing `time` and `device` properties.
7a92810 @argon Updated the readme
authored
106
a847bef @keithnlarsen Make the apn library take a cert and a key as a string instead of as …
keithnlarsen authored
107 var options = {
4476bae @argon Updated Readme to be shorter and more readable.
authored
108 "batchFeedback": true,
109 "interval": 300
a847bef @keithnlarsen Make the apn library take a cert and a key as a string instead of as …
keithnlarsen authored
110 };
7a92810 @argon Updated the readme
authored
111
4476bae @argon Updated Readme to be shorter and more readable.
authored
112 var feedback = new apn.Feedback(options);
113 feedback.on("feedback", function(devices) {
114 devices.forEach(function(item) {
115 // Do something with item.device and item.time;
116 });
117 });
7a92810 @argon Updated the readme
authored
118
4476bae @argon Updated Readme to be shorter and more readable.
authored
119 By specifying a time interval (in seconds) `Feedback` will periodically query the service without further intervention.
5530d7d @argon Lots of Doc. Some Notification helper methods.
authored
120
121 More information about the feedback service can be found in the [feedback service documentation][fs].
122
46b3247 @argon Tidied up debug module loading. Fixed some typos in feedback.js, than…
authored
123 ## Debugging
124
613fbda @argon Clarified the README further.
authored
125 If you experience difficulties sending notifications or using the feedback service you can enable debug messages within the library by running your application with `DEBUG=apn` or `DEBUG=apnfb` set as an environment variable.
46b3247 @argon Tidied up debug module loading. Fixed some typos in feedback.js, than…
authored
126
4476bae @argon Updated Readme to be shorter and more readable.
authored
127 You are encouraged to read the extremely informative [Troubleshooting Push Notifications][tn2265] Tech Note in the first instance, in case your query is answered there.
128
e81cf5b @argon Improved doc.
authored
129 ## Support
130
131 If you have any questions or difficulties working with the module, the [node-apn Google group][googlegroup] should be your first port of call.
132
133 Please include as much detail as possible - especially debug logs, if the problem is reproducible sample code is also extremely helpful. GitHub Issues should only be created for verified problems and enhancements, this will allow them to be tracked more easily.
4476bae @argon Updated Readme to be shorter and more readable.
authored
134
f5f2c89 @argon Added "resources" to Readme.
authored
135 ## Resources
136
137 * [Local and Push Notification Programming Guide: Apple Push Notification Service][pl]
138 * [Apple Technical Note: Troubleshooting Push Notifications][tn2265]
139 * [List of Projects, Applications and Companies Using Node-apn][pacapn]
140
7a92810 @argon Updated the readme
authored
141 ## Credits
142
5530d7d @argon Lots of Doc. Some Notification helper methods.
authored
143 Written and maintained by [Andrew Naylor][andrewnaylor].
7a92810 @argon Updated the readme
authored
144
6c9bbf9 @argon Updated "Thanks to" with Craig Hockenberry.
authored
145 Thanks to: [Ian Babrou][bobrik], [dgthistle][dgthistle], [Keith Larsen][keithnlarsen], [Mike P][mypark], [Greg Bergé][neoziro], [Asad ur Rehman][AsadR], [Nebojsa Sabovic][nsabovic], [Alberto Gimeno][gimenete], [Randall Tombaugh][rwtombaugh], [Michael Stewart][thegreatmichael], [Olivier Louvignes][mgcrea], [porsager][porsager], [Craig Hockenberry][chockenberry]
a55ed78 @argon Readme for v1.1.3
authored
146
7a92810 @argon Updated the readme
authored
147 ## License
148
149 Released under the MIT License
150
61212de @argon Copyright fix.
authored
151 Copyright (c) 2013 Andrew Naylor
7a92810 @argon Updated the readme
authored
152
153 Permission is hereby granted, free of charge, to any person obtaining a copy
154 of this software and associated documentation files (the "Software"), to deal
155 in the Software without restriction, including without limitation the rights
156 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
157 copies of the Software, and to permit persons to whom the Software is
158 furnished to do so, subject to the following conditions:
159
160 The above copyright notice and this permission notice shall be included in
161 all copies or substantial portions of the Software.
162
163 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
164
e81cf5b @argon Improved doc.
authored
165 [certificateWiki]:https://github.com/argon/node-apn/wiki/Preparing-Certificates "Preparing Certificates"
166 [errors]:https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW4 "The Binary Interface and Notification Formats"
167 [pl]: https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html#//apple_ref/doc/uid/TP40008194-CH100-SW1 "Local and Push Notification Programming Guide: Apple Push Notification Service"
168 [fs]: https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW3 "The Feedback Service"
f5f2c89 @argon Added "resources" to Readme.
authored
169 [tn2265]: http://developer.apple.com/library/ios/#technotes/tn2265/_index.html "Troubleshooting Push Notifications"
e81cf5b @argon Improved doc.
authored
170 [googlegroup]:https://groups.google.com/group/node-apn "node-apn Google Group"
f5f2c89 @argon Added "resources" to Readme.
authored
171 [pacapn]:https://github.com/argon/node-apn/wiki/Projects,-Applications,-and-Companies-Using-Node-apn "List of Projects, Applications and Companies Using Node-apn"
5530d7d @argon Lots of Doc. Some Notification helper methods.
authored
172 [andrewnaylor]: http://andrewnaylor.co.uk
a2fc043 @argon Significant improvements to README
authored
173 [bnoordhuis]: http://bnoordhuis.nl
4476bae @argon Updated Readme to be shorter and more readable.
authored
174 [npm]: https://npmjs.org
a55ed78 @argon Readme for v1.1.3
authored
175 [bobrik]: http://bobrik.name
176 [dgthistle]: https://github.com/dgthistle
f97d29d @argon Version 1.1.5
authored
177 [keithnlarsen]: https://github.com/keithnlarsen
178 [mypark]: https://github.com/mypark
43fc54c @argon Updated Readme.md
authored
179 [neoziro]: https://github.com/neoziro
46b3247 @argon Tidied up debug module loading. Fixed some typos in feedback.js, than…
authored
180 [AsadR]: https://github.com/AsadR
1fc5255 @argon Added nsabovic to readme.
authored
181 [nsabovic]: https://github.com/nsabovic
acdbd21 @argon Changed "Contributors" to "Thanks to".
authored
182 [gimenete]: https://github.com/gimenete
25038d5 @argon v1.2.5
authored
183 [rwtombaugh]: https://github.com/rwtombaugh
cb4cb82 @argon v1.2.6
authored
184 [thegreatmichael]: https://github.com/thegreatmichael
185 [mgcrea]: https://github.com/mgcrea
4476bae @argon Updated Readme to be shorter and more readable.
authored
186 [porsager]: https://github.com/porsager
5530d7d @argon Lots of Doc. Some Notification helper methods.
authored
187 [q]: https://github.com/kriskowal/q
6c9bbf9 @argon Updated "Thanks to" with Craig Hockenberry.
authored
188 [chockenberry]: https://github.com/chockenberry
2a93355 @argon Version 1.0.1, now with added changelog!
authored
189
Something went wrong with that request. Please try again.