Pushing Build Status

Pushing is a push notification framework that implements interfaces similar to ActionMailer's APIs.

  • Convention over Configuration: Pushing brings Convention over Configuration to your app's push notification implementation.
  • Extremely Easy to Learn: If you know how to use ActionMailer, you already know how to use Pushing. Send notifications asynchronously with ActiveJob at no learning cost.
  • Testability: First-class support for push notification. No more hassle writing custom code or stubs/mocks for your tests.

Getting Started

Add this line to your application's Gemfile:

gem 'pushing', github: 'yuki24/pushing'
gem 'jbuilder'

As the time of writing, Pushing only has support for jbuilder (Rails' default JSON constructor), but there are plans to add support for jb and rabl.

Supported Client Gems

Pushing itself doesn't make HTTP requests. Instead, it uses an adapter and let an underlaying gem do it. Currently, Pushing has support for the following client gems:

If you are starting from scratch, it is recommended using anpotic for APNs and andpush for FCM due to their reliability and performance:

gem 'apnotic' # APNs integration
gem 'andpush' # FCM integration

Walkthrough to Writing a Notifier

In this README, we'll use Twitter as an example. Suppose you'd like to send a push notification when a user receives a new direct message from other user. To get started, you can use Pushing's notifier generator:

$ rails g pushing:notifier TweetNotifier new_direct_message

Edit the Notifier

Let's say there are direct_messages and device_tokens tables where we store actual messages and device tokens (a.k.a registration ids in FCM) given by APNs or FCM.

# app/notifiers/tweet_notifier.rb
class TweetNotifier < ApplicationNotifier
  def new_direct_message(message_id, token_id)
    @message = DirectMessage.find(message_id)
    @token   = DeviceToken.find(token_id)

    push apn: @token.apn? && @token.device_token, fcm: @token.fcm?
  end
end

Notice that the :apn key takes a truthy string value while the :fcm key takes a boolean value. Also, Pushing only sends a notification for the platforms that are given a truthy value. For example, the call:

# only sends a push notification to FCM
push apn: false, fcm: @token.registration_id

will only send a notification to the FCM service.

Edit the Push Notification Payload

Next, let's modify the templates to generate JSON that contains message data. Like controllers, you can use all the instance variables initialized in the action.

APNs:

# app/views/tweet_notifier/new_direct_message.json+apn.jbuilder
json.aps do
  json.alert do
    json.title "#{@tweet.user.display_name} tweeted:"
    json.body truncate(@tweet.body, length: 235)
  end

  json.badge 1
  json.sound 'bingbong.aiff'
end

FCM:

# app/views/tweet_notifier/new_direct_message.json+fcm.jbuilder
json.to @token.registration_id

json.notification do
  json.title "#{@tweet.user.display_name} tweeted:"
  json.body truncate(@tweet.body, length: 1024)

  json.icon 1
  json.sound 'default'
end

Deliver the Push Notifications

Finally, send a push notification to the user. You can call the #deliver_now! method to immediately send a notification, or the #deliver_later! method if you have ActiveJob set up.

TweetNotifier.new_direct_message(message_id, device_token.id).deliver_now!
# => sends a push notification immediately

TweetNotifier.new_direct_message(message_id, device_token.id).deliver_later!
# => enqueues a job that sends a push notification later

Error Handling

Like ActionMailer, you can use the rescue_from hook to handle exceptions. A common use-case would be to handle a 'BadDeviceToken' response from APNs or a response with a 'Retry-After' header from FCM.

Handling a 'BadDeviceToken' response from APNs:

class ApplicationNotifier < Pushing::Base
  rescue_from Pushing::ApnDeliveryError do |error|
    response = error.response

    if response.status == 410 || (response.status == 400 && response.json[:reason] == 'BadDeviceToken')
      token = error.notification.device_token

      # delete device token accordingly
    else
      raise # Make sure to raise any other types of error to re-enqueue the job
    end
  end
end

Handling a 'Retry-After' header from FCM:

class ApplicationNotifier < Pushing::Base
  rescue_from Pushing::FcmDeliveryError do |error|
    if error.response&.headers['Retry-After']
      # re-enqueue the job honoring the 'Retry-After' header
    else
      raise # Make sure to raise any other types of error to re-enqueue the job
    end
  end
end

Interceptors and Observers

Pushing implements the Interceptor and Observer patterns. A common use-case would be to update registration ids with canonical ids from FCM:

# app/observers/fcm_token_handler.rb
class FcmTokenHandler
  def delivered_notification(payload, response)
    return if response.json[:canonical_ids].to_i.zero?

    response.json[:results].select {|result| result[:registration_id] }.each do |result|
      result[:registration_id] # => returns a canonical id

      # Update registration ids accordingly
    end
  end
end

# app/notifiers/application_notifier.rb
class ApplicationNotifier < Pushing::Base
  register_observer FcmTokenHandler.new

  ...
end

Configuration

TODO

Testing

Pushing provides first-class support for testing. In the test environment, use the :test adapter instead of an actual adapter you'd like to use in development/production.

# config/initializers/pushing.rb
Pushing::Platforms.configure do |config|
  config.apn.adapter = Rails.env.test? ? :test : :apnotic
  config.fcm.adapter = Rails.env.test? ? :test : :andpush
end

Now you can use the #deliveries method. Here is an example with ActiveSupport::TestCase:

TweetNotifier.deliveries.clear # => clears the test inbox

assert_changes -> { TweetNotifier.deliveries.apn.size }, from: 0, to: 1 do
  TweetNotifier.new_direct_message(message.id, apn_device_token.id).deliver_now!
end

apn_message = TweetNotifier.deliveries.apn.first
assert_equal 'apn-device-token',  apn_message.device_token
assert_equal "Hey coffee break?", apn_message.payload[:aps][:alert][:body]

assert_changes -> { TweetNotifier.deliveries.fcm.size }, from: 0, to: 1 do
  TweetNotifier.new_direct_message(message.id, fcm_registration_id.id).deliver_now!
end

fcm_payload = TweetNotifier.deliveries.fcm.first.payload
assert_equal 'fcm-registration-id', fcm_payload[:to]
assert_equal "Hey coffee break?",   fcm_payload[:notification][:body]

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yuki24/pushing. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.