APN on Rails is a Ruby on Rails gem that allows you to easily add Apple Push Notification (iPhone)
support to your Rails application.
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.
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
Put ‘apple_push_notification_production.pem’ in config/
If you are using a development certificate, then change the name to apple_push_notification_development.pem instead.
If you like to use the built in Rails gem management:
Or, if you like to live on the edge:
config.gem 'markbates-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
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:
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. APN on Rails has the following default configurations that you change as you
# 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.
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.
$ ./script/console >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX") >> notification = APN::Notification.new >> notification.device = device >> notification.badge = 5 >> notification.sound = true >> notification.alert = "foobar" >> notification.save
You can use the following Rake task to deliver your notifications:
$ rake apn: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.