Hertz

Hertz is a Ruby on Rails engine for sending in-app notifications to your users.

Installation

Add this line to your application's Gemfile:

gem 'hertz'

And then execute:

$ bundle

Or install it yourself as:

$ gem install hertz

Then, run the installer generator:

$ rails g hertz:install
$ rake db:migrate

Finally, add the following to the model that will receive the notifications (e.g. User):

class User < ActiveRecord::Base
  include Hertz::Notifiable
end

Usage

Using couriers

Couriers are what Hertz uses to deliver notifications to your users. For instance, you might have a courier for delivering notifications by SMS and another one for delivering them by email.

Creating a new courier in Hertz is easy:

module Hertz
  class Sms
    def self.deliver_notification(notification)
      # ...
    end
  end
end

Creating new notification types

In Hertz, every notification is a model. If you want to create a new notification type, just create a new model inheriting from Hertz::Notification:

class CommentNotification < Hertz::Notification
end

Since not all notifications might implement interfaces for all couriers, you have to manually specify which couriers they implement via deliver_by:

class CommentNotification < Hertz::Notification
  deliver_by :sms, :email
end

Notifications are not required to implement any couriers.

You can set common couriers (i.e. couriers that will be used for all notifications) by putting the following into an initializer:

Hertz.configure do |config|
  config.common_couriers = [:sms, :email]
end

Attaching metadata to a notification

You can attach custom metadata to a notification, but make sure it can be cleanly stored in an hstore:

notification = CommentNotification.new(meta: { comment_id: comment.id })
user.notify(notification)

You can then unserialize any data in the model:

class CommentNotification < Hertz::Notification
  def comment
    Comment.find(meta['comment_id'])
  end
end

Note that you should always access your metadata with string keys, regardless of the type you use when attaching it.

Notifying users

You can use #notify for notifying a user:

user.notify(CommentNotification.new(meta: { comment_id: comment.id }))
# or
user.notify(CommentNotification, comment_id: comment.id)

You can access a user's notifications with #notifications:

current_user.notifications
current_user.notifications.read
current_user.notifications.unread

You can also mark notifications as read/unread:

notification.mark_as_read
notification.mark_as_unread

Tracking delivery status

Hertz provides an API couriers can use to mark the notification as delivered. This allows you to know which couriers have successfully delivered your notifications and helps prevent double deliveries:

notification.delivered_with?(:email) # => false
notification.mark_delivered_with(:email) # => Hertz::Delivery
notification.delivered_with?(:email) # => true

Hertz does not enforce usage of the delivery status API in any way, so some couriers may not take advantage of it.

Available couriers

• hertz-twilio: delivers notifications by SMS with the Twilio API.
• hertz-email: delivers notifications by email with ActionMailer.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/aldesantis/hertz.

License

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