- Works with Rails 3 and Ruby 1.9 & 1.8.
- Supports multiple iOS apps.
- Add & remove apps without restarting or affecting the delivery of notifications to other apps.
- Uses a daemon process to keep open persistent connections to the APNs, as recommended by Apple.
- Uses the enhanced binary format so that delivery errors can be reported.
- Records feedback from The Feedback Service.
- Airbrake (Hoptoad) integration.
- Support for dictionary
alertproperties. - Mobile Device Management (MDM)
- Stable. Reconnects to the APNs and your database if connections are lost.
GateGuru, among others!
I'd love to hear if you use rapns - @ileitch on twitter.
Add rapns to your Gemfile:
gem 'rapns'
Generate the migration, rapns.yml and migrate:
rails g rapns
rake db:migrate
-
Open up Keychain Access and select the
Certificatescategory in the sidebar. -
Expand the disclosure arrow next to the iOS Push Services certificate you want to export.
-
Select both the certificate and private key.
-
Right click and select
Export 2 items.... -
Save the file as
cert.p12, make sure the File Format isPersonal Information Exchange (p12). -
If you decide to set a password for your exported certificate, please read the 'Adding Apps' section below.
-
Convert the certificate to a .pem, where
<environment>should bedevelopmentorproduction, depending on the certificate you exported.openssl pkcs12 -nodes -clcerts -in cert.p12 -out <environment>.pem
app = Rapns::App.new
app.key = "my_app"
app.certificate = File.read("/path/to/development.pem")
app.environment = "development"
app.password = "certificate password"
app.connections = 1
app.save!
keyis a symbolic name to tie this app to notifications.certificateis the contents of your PEM certificate, NOT its path on disk.environmentthe certificate type, eitherdevelopmentorproduction.passwordshould be left blank if you did not password protect your certificate.connections(default: 1) the number of connections to keep open to the APNs. Consider increasing this if you are sending a large number of notifications to this app.
cd /path/to/rails/app
bundle exec rapns <Rails environment> [options]
-f--foregroundPrevent rapns from forking into a daemon.-P N--db-poll NFrequency in seconds to check for new notifications. Default: 2.-F N--feedback-poll NFrequency in seconds to check for feedback. Default: 60.-e--no-error-checksDisables error checking after notification delivery. You may want to disable this if you are sending a very high number of notifications.-n--no-airbrake-notifyDisables error notifications via Airbrake.-p PATH--pid-file PATHPath to write PID file. Relative to Rails root unless absolute.-b N--batch-size NActiveRecord batch size of notifications. Increase for possible higher throughput but higher memory footprint. Default: 5000.
n = Rapns::Notification.new
n.app = "my_app"
n.device_token = "934f7a..."
n.alert = "This is the message shown on the device."
n.badge = 1
n.sound = "1.aiff"
n.expiry = 1.day.to_i
n.attributes_for_device = {"question" => nil, "answer" => 42}
n.deliver_after = 1.hour.from_now
n.save!
appmust matchkeyon anRapns::App.sounddefaults to1.aiff. You can either set it to a custom .aiff file, ornilfor no sound.expiryis the time in seconds the APNs (not rapns) will spend trying to deliver the notification to the device. The notification is discarded if it has not been delivered in this time. Default is 1 day.attributes_for_deviceis theNSDictionaryargument passed to your iOS app in eitherdidFinishLaunchingWithOptionsordidReceiveRemoteNotification.deliver_afteris not required, but may be set if you'd like to delay delivery of the notification to a specific time in the future.
n = Rapns::Notification.new
n.mdm = "magic"
n.save!
Please refer to Apple's documentation (Tables 3-1 and 3-2).
If you signal the rapns process with HUP it will synchronize with the current Rapns::App configurations. This includes adding an app, removing and increasing/decreasing the number of connections an app uses.
This synchronization process does not pause the delivery of notifications to other apps.
rapns logs activity to rapns.log in your Rails log directory. This is also printed to STDOUT when running in the foreground. When running as a daemon rapns does not print to STDOUT or STDERR.
The APNs provides two mechanism for delivery failure notification:
Although rapns makes such errors highly unlikely due to validation, the APNs reports processing errors immediately after being sent a notification. These errors are all centred around the well-formedness of the notification payload. Should a notification be rejected due to such an error, rapns will update the following attributes on the notification and send a notification via Airbrake/Hoptoad (if enabled):
failed flag is set to true.
failed_at is set to the time of failure.
error is set to Apple's code for the error.
error_description is set to a (somewhat brief) description of the error.
rapns will not attempt to deliver the notification again.
rapns checks for feedback periodically and stores results in the Rapns::Feedback model. Each record contains the device token and a timestamp of when the APNs determined that the app no longer exists on the device.
It is your responsibility to avoid creating new notifications for devices that no longer have your app installed. rapns does not and will not check Rapns::Feedback before sending notifications.
Note: In my testing and from other reports on the Internet, it appears you may not receive feedback when using the APNs sandbox environment.
After updating you should run rails g rapns to check for any new migrations.
Fork as usual and go crazy!
When running specs, please note that the ActiveRecord adapter can be changed by setting the ADAPTER environment variable. For example: ADAPTER=postgresql rake.
Available adapters for testing are mysql, mysql2 and postgresql.
Thank you to the following wonderful people for contributing to rapns: