Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 180 lines (122 sloc) 8.838 kb
8fc4bf8 @markbates Finished documentation.
markbates authored
1 =APN on Rails (Apple Push Notifications on Rails)
2
3 APN on Rails is a Ruby on Rails gem that allows you to easily add Apple Push Notification (iPhone)
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
4 support to your Rails application.
5
6 It supports:
14897be @PRXci batching finds, fall back to default app, change last_registered_at b…
PRXci authored
7 * Multiple iPhone apps managed from the same Rails application as well as a legacy default "app" with certs stored in config
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
8 * Individual notifications and group notifications
9 * Alerts, badges, sounds, and custom properties in notifications
e1cf929 @PRXci updating READMEs
PRXci authored
10 * Pull notifications
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
11
12 == Feature Descriptions
13
14 Multiple iPhone Apps: In previous versions of this gem a single Rails application was set up to
15 manage push notifications for a single iPhone app. In many cases it is useful to have a single Rails
16 app manage push notifications for multiple iPhone apps. With the addition of an APN::App model, this
14897be @PRXci batching finds, fall back to default app, change last_registered_at b…
PRXci authored
17 is now possible. The certificates are now stored on instances of APN::App and devices are intended to be associated
18 with a particular app. For compatibility with existing implementations it is still possible to create devices that
19 are not associated with an APN::App and to send individual notifications to them using the certs stored in the
20 config directory.
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
21
22 Individual and Group Notifications: Previous versions of this gem treated each notification individually
23 and did not provide a built-in way to send a broadcast notification to a group of devices. Group notifications
24 are now built into the gem. A group notification is associated with a group of devices and shares its
14897be @PRXci batching finds, fall back to default app, change last_registered_at b…
PRXci authored
25 contents across the entire group of devices. (Group notifications are only available for groups of devices associated
26 with an APN::App)
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
27
28 Notification Content Areas: Notifications may contain alerts, badges, sounds, and custom properties.
29
e1cf929 @PRXci updating READMEs
PRXci authored
30 Pull Notifications: This version of the gem supports an alternative notification method that relies
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
31 on pulls from client devices and does not interact with the Apple Push Notification servers. This feature
e1cf929 @PRXci updating READMEs
PRXci authored
32 may be used entirely independently of the push notification features. Pull notifications may be
33 created for an app. A client app can query for the most recent pull notification available since a
14897be @PRXci batching finds, fall back to default app, change last_registered_at b…
PRXci authored
34 given date to retrieve any notifications waiting for it.
35
36 ==Version 0.4.1 Notes
37
38 * Backwards compatibility. 0.4.0 required a manual upgrade to associate existing and new devices with an APN::App model. This version allows continued use of devices that are associated with a default "app" that stores its certificates in the config directory. This ought to allow upgrade to this version without code changes.
39 * Batched finds. Finds on the APN::Device model that can return large numbers of records have been batched to limit memory impact.
40 * Custom properties migration. At a pre-0.4.0 version the custom_properties attribute was added to the migration template that created the notifications table. This introduced a potential problem for gem users who had previously run this migration. The custom_properties alteration to the apn_notifications table has been moved to its own migration and should work regardless of whether your apn_notifications table already has a custom_properties attribute.
41 * last_registered_at changed to work intuitively. The last_registered_at attribute of devices was being updated only on creation potentially causing a bug in which a device that opts out of APNs and then opts back in before apn_on_rails received feedback about it might miss a period of APNs that it should receive.
8fc4bf8 @markbates Finished documentation.
markbates authored
42
43 ==Acknowledgements:
85e318a @markbates Added tests for the apple_hash method
markbates authored
44
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
45 From Mark Bates:
46
68ae1d8 @markbates Added documentation.
markbates authored
47 This gem is a re-write of a plugin that was written by Fabien Penso and Sam Soffes.
48 Their plugin was a great start, but it just didn't quite reach the level I hoped it would.
49 I've re-written, as a gem, added a ton of tests, and I would like to think that I made it
50 a little nicer and easier to use.
85e318a @markbates Added tests for the apple_hash method
markbates authored
51
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
52 From Rebecca Nesson (PRX.org):
53
54 This gem extends the original version that Mark Bates adapted. His gem did the hard
55 work of setting up and handling all communication with the Apple push notification servers.
56
8fc4bf8 @markbates Finished documentation.
markbates authored
57 ==Converting Your Certificate:
58
85e318a @markbates Added tests for the apple_hash method
markbates authored
59 Once you have the certificate from Apple for your application, export your key
60 and the apple certificate as p12 files. Here is a quick walkthrough on how to do this:
61
62 1. Click the disclosure arrow next to your certificate in Keychain Access and select the certificate and the key.
63 2. Right click and choose `Export 2 items...`.
64 3. Choose the p12 format from the drop down and name it `cert.p12`.
65
66 Now covert the p12 file to a pem file:
67
68ae1d8 @markbates Added documentation.
markbates authored
68 $ openssl pkcs12 -in cert.p12 -out apple_push_notification_production.pem -nodes -clcerts
69
70 If you are using a development certificate, then change the name to apple_push_notification_development.pem instead.
85e318a @markbates Added tests for the apple_hash method
markbates authored
71
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
72 Store the contents of the certificate files on the app model for the app you want to send notifications to.
73
8fc4bf8 @markbates Finished documentation.
markbates authored
74 ==Installing:
75
76 ===Stable (RubyForge):
85e318a @markbates Added tests for the apple_hash method
markbates authored
77
68ae1d8 @markbates Added documentation.
markbates authored
78 $ sudo gem install apn_on_rails
79
8fc4bf8 @markbates Finished documentation.
markbates authored
80 ===Edge (GitHub):
81
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
82 $ sudo gem install PRX-apn_on_rails.git --source=http://gems.github.com
8fc4bf8 @markbates Finished documentation.
markbates authored
83
84 ===Rails Gem Management:
68ae1d8 @markbates Added documentation.
markbates authored
85
86 If you like to use the built in Rails gem management:
8fc4bf8 @markbates Finished documentation.
markbates authored
87
68ae1d8 @markbates Added documentation.
markbates authored
88 config.gem 'apn_on_rails'
89
90 Or, if you like to live on the edge:
8fc4bf8 @markbates Finished documentation.
markbates authored
91
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
92 config.gem 'PRX-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
8fc4bf8 @markbates Finished documentation.
markbates authored
93
94 ==Setup and Configuration:
95
96 Once you have the gem installed via your favorite gem installation, you need to require it so you can
97 start to use it:
98
99 Add the following require, wherever it makes sense to you:
100
101 require 'apn_on_rails'
102
103 You also need to add the following to your Rakefile so you can use the
68ae1d8 @markbates Added documentation.
markbates authored
104 Rake tasks that ship with APN on Rails:
8fc4bf8 @markbates Finished documentation.
markbates authored
105
68ae1d8 @markbates Added documentation.
markbates authored
106 begin
107 require 'apn_on_rails_tasks'
108 rescue MissingSourceFile => e
109 puts e.message
110 end
111
112 Now, to create the tables you need for APN on Rails, run the following task:
8fc4bf8 @markbates Finished documentation.
markbates authored
113
7f2d342 @markbates Updated README
markbates authored
114 $ ruby script/generate apn_migrations
85e318a @markbates Added tests for the apple_hash method
markbates authored
115
525710c @markbates Updated README
markbates authored
116 APN on Rails uses the Configatron gem, http://github.com/markbates/configatron/tree/master,
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
117 to configure itself. (With the change to multi-app support, the certifications are stored in the
14897be @PRXci batching finds, fall back to default app, change last_registered_at b…
PRXci authored
118 database rather than in the config directory, however, it is still possible to use the default "app" and the certificates
119 stored in the config directory. For this setup, the following configurations apply.)
120 APN on Rails has the following default configurations that you change as you see fit:
525710c @markbates Updated README
markbates authored
121
1bdf183 @markbates Finished documentation for feedback integration.
markbates authored
122 # development (delivery):
525710c @markbates Updated README
markbates authored
123 configatron.apn.passphrase # => ''
124 configatron.apn.port # => 2195
125 configatron.apn.host # => 'gateway.sandbox.push.apple.com'
126 configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
127
1bdf183 @markbates Finished documentation for feedback integration.
markbates authored
128 # production (delivery):
525710c @markbates Updated README
markbates authored
129 configatron.apn.host # => 'gateway.push.apple.com'
130 configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
1bdf183 @markbates Finished documentation for feedback integration.
markbates authored
131
132 # development (feedback):
133 configatron.apn.feedback.passphrase # => ''
134 configatron.apn.feedback.port # => 2196
135 configatron.apn.feedback.host # => 'feedback.sandbox.push.apple.com'
136 configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
137
138 # production (feedback):
139 configatron.apn.feedback.host # => 'feedback.push.apple.com'
140 configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
525710c @markbates Updated README
markbates authored
141
68ae1d8 @markbates Added documentation.
markbates authored
142 That's it, now you're ready to start creating notifications.
85e318a @markbates Added tests for the apple_hash method
markbates authored
143
3b50ff1 @markbates Nearly done with feedback. Just adding documentation.
markbates authored
144 ===Upgrade Notes:
145
146 If you are upgrading to a new version of APN on Rails you should always run:
147
148 $ ruby script/generate apn_migrations
149
150 That way you ensure you have the latest version of the database tables needed.
151
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
152 ==Example (assuming you have created an app and stored your keys on it):
8fc4bf8 @markbates Finished documentation.
markbates authored
153
154 $ ./script/console
14897be @PRXci batching finds, fall back to default app, change last_registered_at b…
PRXci authored
155 >> app = APN::App.create(:name => "My App", :apn_dev_cert => "PASTE YOUR DEV CERT HERE", :apn_prod_cert => "PASTE YOUR PROD CERT HERE")
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
156 >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX",:app_id => app.id)
8fc4bf8 @markbates Finished documentation.
markbates authored
157 >> notification = APN::Notification.new
158 >> notification.device = device
159 >> notification.badge = 5
160 >> notification.sound = true
161 >> notification.alert = "foobar"
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
162 >> notification.custom_properties = {:link => "http://www.prx.org"}
8fc4bf8 @markbates Finished documentation.
markbates authored
163 >> notification.save
164
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
165 You can use the following Rake task to deliver your individual notifications:
8fc4bf8 @markbates Finished documentation.
markbates authored
166
167 $ rake apn:notifications:deliver
525710c @markbates Updated README
markbates authored
168
43c8492 @PRXci working on tests, adding in all my changes
PRXci authored
169 And the following task to deliver your group notifications:
170
171 $ rake apn:group_notifications:deliver
172
d5299bb @markbates Updated section in README about delivering notifications.
markbates authored
173 The Rake task will find any unsent notifications in the database. If there aren't any notifications
174 it will simply do nothing. If there are notifications waiting to be delivered it will open a single connection
175 to Apple and push all the notifications through that one connection. Apple does not like people opening/closing
176 connections constantly, so it's pretty important that you are careful about batching up your notifications so
177 Apple doesn't shut you down.
178
525710c @markbates Updated README
markbates authored
179 Released under the MIT license.
Something went wrong with that request. Please try again.