Pushing
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 (, token_id)
@message = DirectMessage.find()
@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.(, device_token.id).deliver_now!
# => sends a push notification immediately
TweetNotifier.(, 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.(.id, apn_device_token.id).deliver_now!
end
= TweetNotifier.deliveries.apn.first
assert_equal 'apn-device-token', .device_token
assert_equal "Hey coffee break?", .payload[:aps][:alert][:body]
assert_changes -> { TweetNotifier.deliveries.fcm.size }, from: 0, to: 1 do
TweetNotifier.(.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.