Gem Version Dependency Status Code Climate

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


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


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
  module Courier
    class Sms
      def self.deliver_notification(notification)
        # ...

Again, you don't have to use couriers if you only display notifications on your website using standard AR methods.

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

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

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]

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 })

You can then unserialize any data in the model:

class CommentNotification < Hertz::Notification
  def comment

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:


You can also mark notifications as read/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 API in any way, so some couriers might not take advantage of it.

Available couriers


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


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