README.md

ActivityNotification

activity_notification provides integrated user activity notifications for Ruby on Rails. You can easily use it to configure multiple notification targets and make activity notifications with notifiable models, like adding comments, responding etc.

activity_notification supports Rails 5.0+ with ActiveRecord, Mongoid and Dynamoid ORM. It is tested for MySQL, PostgreSQL, SQLite3 with ActiveRecord, MongoDB with Mongoid and Amazon DynamoDB with Dynamoid. If you are using Rails 4.2, use v2.1.4 or older version of activity_notification.

About

activity_notification provides following functions:

• Notification API for your Rails application (creating and managing notifications, query for notifications)
• Notification models (stored with ActiveRecord, Mongoid or Dynamoid ORM)
• Notification controllers (managing open/unopen of notifications, providing link to notifiable activity page)
• Notification views (presentation of notifications)
• Automatic tracked notifications (generating notifications along with the lifecycle of notifiable models)
• Grouping notifications (grouping like "Kevin and 7 other users posted comments to this article")
• Email notification
• Batch email notification (event driven or periodical email notification, daily or weekly etc)
• Push notification with Action Cable
• Subscription management (subscribing and unsubscribing for each target and notification type)
• REST API backend and OpenAPI Specification
• Integration with Devise authentication
• Activity notifications stream integrated into cloud computing using Amazon DynamoDB Streams
• Optional notification targets (Configurable optional notification targets like Amazon SNS, Slack, SMS and so on)

Online Demo

You can see an actual application using this gem here:

• https://activity-notification-example.herokuapp.com/

Login as the following test users to experience user activity notifications:

Email	Password	Admin?
ichiro@example.com	changeit	Yes
stephen@example.com	changeit
klay@example.com	changeit
kevin@example.com	changeit

The deployed demo application is included in this gem's source code as a test application here: /spec/rails_app

Notification index and plugin notifications

activity_notification deeply uses PublicActivity as reference in presentation layer.

Subscription management of notifications

Amazon SNS as optional notification target

Slack as optional notification target

Public REST API reference as OpenAPI Specification

REST API reference as OpenAPI Specification is published in SwaggerHub here:

• https://app.swaggerhub.com/apis-docs/simukappu/activity-notification/

You can see sample single page application using Vue.js as a part of example Rails application here:

• https://activity-notification-example.herokuapp.com/spa/

This sample application works with activity_notification REST API backend.

Table of Contents

• About
  • Online Demo
  • Public REST API reference as OpenAPI Specification
• Getting Started
• Setup
  • Gem installation
  • Database setup
    • Using ActiveRecord ORM
    • Using Mongoid ORM
    • Using Dynamoid ORM
      • Integration with DynamoDB Streams
  • Configuring models
    • Configuring target models
    • Configuring notifiable models
      • Advanced notifiable path
  • Configuring views
  • Configuring routes
    • Routes with scope
    • Routes as REST API backend
  • Creating notifications
    • Notification API
    • Asynchronous notification API with ActiveJob
    • Automatic tracked notifications
  • Displaying notifications
    • Preparing target notifications
    • Rendering notifications
    • Notification views
    • i18n for notifications
  • Customizing controllers (optional)
• Functions
  • Email notification
    • Mailer setup
    • Sender configuration
    • Email templates
    • Email subject
    • Other header fields
    • i18n for email
  • Batch email notification
    • Batch mailer setup
    • Batch sender configuration
    • Batch email templates
    • Batch email subject
    • i18n for batch email
  • Grouping notifications
  • Subscription management
    • Configuring subscriptions
    • Managing subscriptions
    • Customizing subscriptions
  • REST API backend
    • Configuring REST API backend
    • API reference as OpenAPI Specification
  • Integration with Devise
    • Configuring integration with Devise authentication
    • Using different model as target
    • Configuring simple default routes
    • REST API backend with Devise Token Auth
  • Push notification with Action Cable
    • Enabling broadcasting notifications to channels
    • Subscribing notifications from channels
    • Subscribing notifications with Devise authentication
    • Subscribing notifications API with Devise Token Auth
    • Subscription management of Action Cable channels
  • Optional notification targets
    • Configuring optional targets
    • Customizing message format
    • Action Cable channels as optional target
    • Amazon SNS as optional target
    • Slack as optional target
    • Developing custom optional targets
    • Subscription management of optional targets
• Testing
  • Testing your application
  • Testing gem alone
• Documentation
• Common Examples
• Contributing
• License

Getting Started

This getting started shows easy setup description of activity_notification. See Setup for more details.

Gem installation

You can install activity_notification as you would any other gem:

$ gem install activity_notification

or in your Gemfile:

gem 'activity_notification'

After you install activity_notification and add it to your Gemfile, you need to run the generator:

$ bin/rails generate activity_notification:install

The generator will install an initializer which describes all configuration options of activity_notification.

Database setup

When you use activity_notification with ActiveRecord ORM as default configuration, create migration for notifications and migrate the database in your Rails project:

$ bin/rails generate activity_notification:migration
$ bin/rake db:migrate

See Database setup for other ORMs.

Configuring models

Configure your target model (e.g. app/models/user.rb). Add acts_as_target configuration to your target model to get notifications.

class User < ActiveRecord::Base
  acts_as_target
end

Then, configure your notifiable model (e.g. app/models/comment.rb). Add acts_as_notifiable configuration to your notifiable model representing activity to notify for each of your target model. You have to define notification targets for all notifications from this notifiable model by :targets option. Other configurations are optional. :notifiable_path option is a path to move when the notification is opened by the target user.

class Article < ActiveRecord::Base
  belongs_to :user
  has_many :comments, dependent: :destroy
  has_many :commented_users, through: :comments, source: :user
end

class Comment < ActiveRecord::Base
  belongs_to :article
  belongs_to :user

  acts_as_notifiable :users,
    targets: ->(comment, key) {
      ([comment.article.user] + comment.article.reload.commented_users.to_a - [comment.user]).uniq
    },
    notifiable_path: :article_notifiable_path

  def article_notifiable_path
    article_path(article)
  end
end

See Configuring models for more details.

Configuring views

activity_notification provides view templates to customize your notification views. See Configuring views for more details.

Configuring routes

activity_notification also provides routing helper for notifications. Add notify_to method to config/routes.rb for the target (e.g. :users):

Rails.application.routes.draw do
  notify_to :users
end

See Configuring routes for more details.

You can also configure activity_notification routes as REST API backend with api_mode option like this:

Rails.application.routes.draw do
  scope :api do
    scope :"v2" do
      notify_to :users, api_mode: true
    end
  end
end

See Routes as REST API backend and REST API backend for more details.

Creating notifications

You can trigger notifications by setting all your required parameters and triggering notify on the notifiable model, like this:

@comment.notify :users, key: "comment.reply"

The first argument is the plural symbol name of your target model, which is configured in notifiable model by acts_as_notifiable. The new instances of ActivityNotification::Notification model will be generated for the specified targets.

See Creating notifications for more details.

Displaying notifications

activity_notification also provides notification views. You can prepare target notifications, render them in your controller, and show them provided or custom notification views.

See Displaying notifications for more details.

Run example Rails application

Test module includes example Rails application in spec/rails_app. Pull git repository and you can run the example application as common Rails application.

$ git pull https://github.com/simukappu/activity_notification.git
$ cd activity_notification
$ bundle install —path vendor/bundle
$ cd spec/rails_app
$ bin/rake db:migrate
$ bin/rake db:seed
$ bin/rails server

Then, you can access http://localhost:3000 for the example application.

Setup

See Setup.

Functions

See Functions.

Testing

See Testing.

Documentation

See API Reference for more details.

RubyDoc.info does not support parsing methods in included and class_methods of ActiveSupport::Concern currently. To read complete documents, please generate YARD documents on your local environment:

$ git pull https://github.com/simukappu/activity_notification.git
$ cd activity_notification
$ bundle install —path vendor/bundle
$ bundle exec yard doc
$ bundle exec yard server

Then you can see the documents at http://localhost:8808/docs/index.

Common Examples

See example Rails application in /spec/rails_app.

You can also try this example Rails application as Online Demo here:

• https://activity-notification-example.herokuapp.com/

You can login as test users to experience user activity notifications. For more details, see Online Demo.

Contributing

We encourage you to contribute to activity_notification! Please check out the Contributing to activity_notification guide for guidelines about how to proceed.

Everyone interacting in activity_notification codebases, issue trackers, and pull requests is expected to follow the activity_notification Code of Conduct.

We appreciate any of your contribution!

License

activity_notification project rocks and uses MIT License.