Build Status Code Climate Code Coverage Gem Version

Rpush. The push notification service for Ruby.

  • Supported services:

    • Apple Push Notification Service
    • Google Cloud Messaging
    • Amazon Device Messaging
    • Windows Phone Push Notification Service

  • Supported storage backends:

    • ActiveRecord
    • Redis
    • More coming soon!

  • Seamless Rails (3, 4) integration.

  • Scales vertically (threading) and horizontally (multiple processes).

  • Designed for uptime - new apps are loaded automatically, signal HUP to update running apps.

  • Run as a daemon or inside an existing process.

  • Use in a scheduler for low-workload deployments (Push API).

  • Hooks for fine-grained instrumentation and error handling (Reflection API).

  • Works with MRI, JRuby and Rubinius.

Getting Started

Add it to your Gemfile:

gem 'rpush'

Generate the migrations, rpush.rb and migrate:

rails g rpush
rake db:migrate

Create an App & Notification

Apple Push Notification Service

If this is your first time using the APNs, you will need to generate SSL certificates. See Generating Certificates for instructions.

app = Rpush::Apns::App.new
app.name = "ios_app"
app.certificate = File.read("/path/to/sandbox.pem")
app.environment = "sandbox" # 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 = "..."
n.alert = "hi mom!"
n.data = { foo: :bar }
n.save!

You should also implement the ssl_certificate_will_expire reflection to monitor when your certificate is due to expire.

Google Cloud Messaging

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 = ["token", "..."]
n.data = { message: "hi mom!" }
n.save!

GCM also requires you to respond to Canonical IDs.

Amazon Device Messaging

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

app = Rpush::Wpns::App.new
app.name = "windows_phone_app"
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.alert = "..."
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.

cd /path/to/rails/app
rpush <Rails environment> [options]

Embedded inside an existing process

# Call this during startup of your application, for example, by adding it to the end of config/initializers/rpush.rb
Rpush.embed

See Embedding API for more details.

Manually (in a scheduler)

Rpush.push
Rpush.apns_feedback

See Push API for more details.

Configuration

See Configuration for a list of options, or run rpush --help.

Updating Rpush

If you're using ActiveRecord, you should run rails g rpush after upgrading Rpush to check for any new migrations.

Wiki

General

Apple Push Notification Service

Google Cloud Messaging

Contributing

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.

Note that the database username is changed at runtime to be the currently logged in user's name. So if you're testing with mysql and you're using a user named 'bob', you will need to grant a mysql user 'bob' access to the 'rpush_test' mysql database.