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.
Acknowledgements:
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.
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:
-
Click the disclosure arrow next to your certificate in Keychain Access and select the certificate and the key.
-
Right click and choose ‘Export 2 items…`.
-
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.
Installing:
Stable (RubyForge):
$ sudo gem install apn_on_rails
Edge (GitHub):
$ sudo gem install markbates-apn_on_rails --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 'markbates-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.
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, github.com/markbates/configatron/tree/master, to configure itself. APN on Rails has the following default configurations that you change as you see fit:
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:
configatron.apn.host # => 'gateway.push.apple.com'
configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
That’s it, now you’re ready to start creating notifications.
Example:
$ ./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
>> APN::Notification.send_notifications
You can also run the following Rake task to send your notifications:
$ rake apn:notifications:deliver
Released under the MIT license.