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