Rpush. The push notification service for Ruby.
Rpush aims to be the de facto gem for sending push notifications in Ruby. Its core goals are ease of use, reliability and a rich feature set. Rpush provides numerous advanced features not found in others gems, giving you greater control & insight as your project grows. These are a few of the reasons why companies worldwide rely on Rpush to deliver their notifications.
Feature Highlights
- Use ActiveRecord or Redis for storage.
- Plugins for Bugsnag, Sentry, StatsD. Third party plugins: Prometheus Exporter. Or write your own.
- Seamless integration with your projects, including Rails.
- Run as a daemon, inside a job queue, on the command-line or embedded in another process.
- Scales vertically (threading) and horizontally (multiple processes).
- Designed for uptime - new apps are loaded automatically, signal
HUP
to update running apps. - Hooks for fine-grained instrumentation and error handling (Reflection API).
- Tested with MRI
Getting Started
Add it to your Gemfile:
gem 'rpush'
Initialize Rpush into your project. Rails will be detected automatically.
$ cd /path/to/project
$ bundle
$ bundle exec rpush init
Create an App & Notification
Apnsp8
To use the p8 APNs Api:
app = Rpush::Apnsp8::App.new
app.name = "ios_app"
app.apn_key = File.read("/path/to/sandbox.p8")
app.environment = "development" # APNs environment.
app.apn_key_id = "APN KEY ID" # This is the Encryption Key ID provided by apple
app.team_id = "TEAM ID" # the team id - e.g. ABCDE12345
app.bundle_id = "BUNDLE ID" # the unique bundle id of the app, like com.example.appname
app.connections = 1
app.save!
n = Rpush::Apnsp8::Notification.new
n.app = Rpush::Apnsp8::App.find_by_name("ios_app")
n.device_token = "..." # hex string
n.alert = "hi mom!"
n.data = { foo: :bar }
n.save!
Apns2
(NB this uses the same protocol as Apnsp8, but authenticates with a certificate rather than tokens)
app = Rpush::Apns2::App.new
app.name = "ios_app"
app.certificate = File.read("/path/to/sandbox.pem")
app.environment = "development"
app.password = "certificate password"
app.bundle_id = "BUNDLE ID" # the unique bundle id of the app, like com.example.appname
app.connections = 1
app.save!
n = Rpush::Apns2::Notification.new
n.app = Rpush::Apns2::App.find_by_name("ios_app")
n.device_token = "..." # hex string
n.alert = "hi mom!"
n.data = {
headers: { 'apns-topic': "BUNDLE ID" }, # the bundle id of the app, like com.example.appname. Not necessary if set on the app (see above)
foo: :bar
}
n.save!
You should also implement the ssl_certificate_will_expire reflection to monitor when your certificate is due to expire.
Apns (legacy protocol)
app = Rpush::Apns::App.new
app.name = "ios_app"
app.certificate = File.read("/path/to/sandbox.pem")
app.environment = "development" # APNs environment.
app.password = "certificate password"
app.connections = 1
app.save!
n = Rpush::Apns::Notification.new
n.app = Rpush::Apns::App.find_by_name("ios_app")
n.device_token = "..." # hex string
n.alert = "hi mom!"
n.data = { foo: :bar }
n.save!
Safari Push Notifications
Using one of the notifications methods above, the url_args
attribute is available for Safari Push Notifications.
Environment
The app environment
for any Apns* option is “development” for XCode installs, and “production” for app store and TestFlight. Note that for Apns2 you can now use one (production + sandbox) certificate (you don’t need a separate “sandbox” or development certificate), but if you do generate a development/sandbox certificate it can only be used for “development”. With Apnsp8 tokens, you can target either “development” or “production” environments.
Firebase Cloud Messaging
FCM and GCM are – as of writing – compatible with each other. See also this comment for further references.
Please refer to the Firebase Console on where to find your auth_key
(probably called Server Key there). To verify you have the right key, use tools like Postman, HTTPie, curl
or similar before reporting a new issue. See also this comment.
app = Rpush::Gcm::App.new
app.name = "android_app"
app.auth_key = "..."
app.connections = 1
app.save!
n = Rpush::Gcm::Notification.new
n.app = Rpush::Gcm::App.find_by_name("android_app")
n.registration_ids = ["..."]
n.data = { message: "hi mom!" }
n.priority = 'high' # Optional, can be either 'normal' or 'high'
n.content_available = true # Optional
#### Amazon Device Messaging
```ruby
app = Rpush::Adm::App.new
app.name = "kindle_app"
app.client_id = "..."
app.client_secret = "..."
app.connections = 1
app.save!
n = Rpush::Adm::Notification.new
n.app = Rpush::Adm::App.find_by_name("kindle_app")
n.registration_ids = ["..."]
n.data = { message: "hi mom!"}
n.collapse_key = "Optional consolidationKey"
n.save!
For more documentation on ADM.
Windows Phone Notification Service (Windows Phone 8.0 and 7.x)
Uses the older Windows Phone 8 Toast template
app = Rpush::Wpns::App.new
app.name = "windows_phone_app"
app.client_id = # Get this from your apps dashboard https://dev.windows.com
app.client_secret = # Get this from your apps dashboard https://dev.windows.com
app.connections = 1
app.save!
n = Rpush::Wpns::Notification.new
n.app = Rpush::Wpns::App.find_by_name("windows_phone_app")
n.uri = "http://..."
n.data = {title:"MyApp", body:"Hello world", param:"user_param1"}
n.save!
Windows Notification Service (Windows 8.1, 10 Apps & Phone > 8.0)
Uses the more recent Toast template
The client_id
here is the SID URL as seen here. Do not confuse it with the client_id
on dashboard.
You can (optionally) include a launch argument by adding a launch
key to the notification data.
You can (optionally) include an audio element by setting the sound on the notification.
app = Rpush::Wns::App.new
app.name = "windows_phone_app"
app.client_id = YOUR_SID_URL
app.client_secret = YOUR_CLIENT_SECRET
app.connections = 1
app.save!
n = Rpush::Wns::Notification.new
n.app = Rpush::Wns::App.find_by_name("windows_phone_app")
n.uri = "http://..."
n.data = {title:"MyApp", body:"Hello world", launch:"launch-argument"}
n.sound = "ms-appx:///mynotificationsound.wav"
n.save!
Windows Badge Push Notifications
Uses the badge template and the type wns/badge
.
n = Rpush::Wns::BadgeNotification.new
n.app = Rpush::Wns::App.find_by_name("windows_phone_app")
n.uri = 'http://...'
n.badge = 4
n.save!
Running Rpush
It is recommended to run Rpush as a separate process in most cases, though embedding and manual modes are provided for low-workload environments.
See rpush help
for all available commands and options.
As a daemon
$ cd /path/to/project
$ rpush start
As a foreground process
$ cd /path/to/project
$ rpush start -f
On the command-line
$ rpush push
Rpush will deliver all pending notifications and then exit.
In a scheduled job
Rpush.push
Rpush.apns_feedback
See Push API for more details.
Using mina
If you’re using mina, there is a gem called mina-rpush which helps you control rpush.
Cleanup
Rpush leaves delivered notifications in the database. If you do not clear them out, they will take up more and more space. This isn’t great for any database, but is especially problematic if using Redis as the Rpush store. Here is an example solution for cleaning up delivered notifications in Redis.
Configuration
See Configuration for a list of options.
Updating Rpush
You should run rpush init
after upgrading Rpush to check for configuration and migration changes.
From The Wiki
General
- Using Redis
- Using ActiveRecord
- Configuration
- Moving from Rapns
- Deploying to Heroku
- Hot App Updates
- Signals
- Reflection API
- Push API
- Embedding API
- Writing a Plugin
- Implementing your own storage backend
- Upgrading from 2.x to 3.0
Apple Push Notification Service
- Generating Certificates
- Advanced APNs Features
- APNs Delivery Failure Handling
- Why open multiple connections to the APNs?
- Silent failures might be dropped connections
Firebase Cloud Messaging
Running Tests
Rpush uses Appraisal to run tests against multiple versions of Ruby on Rails. This helps making sure that Rpush performs correctly with multiple Rails versions.
Rpush also uses RSpec for its tests.
Bootstrapping your test suite:
First, we need to setup a test database, rpush_test
.
E.g. (postgres): psql -c 'create database rpush_test;' -U postgres >/dev/null
bundle install
bundle exec appraisal install
This will install all the required gems that requires to test against each version of Rails, which defined in gemfiles/*.gemfile
.
To run a full test suite:
bundle exec appraisal rake
This will run RSpec against all versions of Rails.
To run a single test
You need to specify a BUNDLE_GEMFILE
pointing to the gemfile before running the normal test command:
BUNDLE_GEMFILE=gemfiles/rails_5.2.gemfile rspec spec/unit/apns_feedback_spec.rb