[Awesome Ruby Gem] Use rpush gem to push notify to notification service

Posted on Edited on In , , Views: Word count in article: 6.2k Reading time ≈ 6 mins.

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.

Supported Services

  • Apple Push Notification Service

    Including Safari Push Notifications.

  • Firebase Cloud Messaging (used to be Google Cloud Messaging)

  • Amazon Device Messaging

  • Windows Phone Push Notification Service

  • Pushy

  • Webpush

Feature Highlights

  • Use ActiveRecord or Redis for storage.

  • Plugins for Bugsnag, Sentry, StatsD 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

Installation

You can install it as a gem:

1
$ gem install rpush

or add it into a Gemfile (Bundler):

1
2
3
4
5
# Gemfile

# rpush/rpush: The push notification service for Ruby.
# https://github.com/rpush/rpush
gem 'rpush', `6.0.0'

Then, run bundle install.

1
$ bundle install

Usages

Create an App & Notification

Apple Push Notification Service

There is a choice of two modes (and one legacy mode) using certificates or using tokens:

If this is your first time using the APNs, you will need to generate either SSL certificates (for Apns2 or Apns) or an Encryption Key (p8) and an Encryption Key ID (for Apnsp8). See Generating Certificates - https://github.com/rpush/rpush/wiki/Generating-Certificates for instructions.

Apnsp8

To use the p8 APNs Api:

1
2
3
4
5
6
7
8
9
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!
1
2
3
4
5
6
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)

1
2
3
4
5
6
7
8
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!
1
2
3
4
5
6
7
8
9
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!

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.

1
2
3
4
5
app = Rpush::Gcm::App.new
app.name = "android_app"
app.auth_key = "..."
app.connections = 1
app.save!
1
2
3
4
5
6
7
8
9
10
11
12
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
# Optional notification payload. See the reference below for more keys you can use!
n.notification = { body: 'great match!',
                   title: 'Portugal vs. Denmark',
                   icon: 'myicon'
                 }
n.save!

FCM also requires you to respond to Canonical IDs - https://github.com/rpush/rpush/wiki/Canonical-IDs.

Amazon Device Messaging

1
2
3
4
5
6
app = Rpush::Adm::App.new
app.name = "kindle_app"
app.client_id = "..."
app.client_secret = "..."
app.connections = 1
app.save!
1
2
3
4
5
6
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 - https://developer.amazon.com/sdk/adm.html.

See Create an App & Notification - https://github.com/rpush/rpush#create-an-app–notification to learn more.

Check the FCM reference - https://firebase.google.com/docs/cloud-messaging/http-server-ref#notification-payload-support for what keys you can use and are available to you. Note: Not all are yet implemented in Rpush.

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

1
2
$ cd /path/to/project
$ rpush start

As a foreground process

1
2
$ cd /path/to/project
$ rpush start -f

On the command-line

1
$ rpush push

Rpush will deliver all pending notifications and then exit.

In a scheduled job

1
2
Rpush.push
Rpush.apns_feedback

See Push API for more details.

Embedded inside an existing process

1
2
3
4
5
6
7
if defined?(Rails)
  ActiveSupport.on_load(:after_initialize) do
    Rpush.embed
  end
else
  Rpush.embed
end

Call this during startup of your application, for example, by adding it to the end of config/rpush.rb. See Embedding API for more details.

Configuration
See Configuration · rpush/rpush Wiki - https://github.com/rpush/rpush/wiki/Configuration for a list of options.

References

[1] rpush/rpush: The push notification service for Ruby. - https://github.com/rpush/rpush

[2] rpush | RubyGems.org | your community gem host - https://rubygems.org/gems/rpush

[3] Configuration · rpush/rpush Wiki - https://github.com/rpush/rpush/wiki/Configuration