notify_user

Install:

gem 'notify_user'
rails g notify_user:install

Getting started:

rails g notify_user:notification NewMyProperty

Edit views/notify_user/new_my_property/action_mailer/notification.html.erb, e.g.

<h3>We added <%= @notification.params[:listing_address] %> to your My Properties.</h3>

Then send:

NotifyUser.send_notification('new_my_property').to(user).with("listing_address" => "123 Main St").notify

Dynamic email titles use %tags that correspond to your params hash (Will throw an exception if key is missing)

channel :action_mailer,
      subject: "%{name} sent you a message",
      aggregate: {
        subject: "%{name} sent you %{count} messages"
      }

To enable APNS add this line to your app/notification/notification_type.rb

channel :apns,
    aggregate_per: false

To run the tests:

BUNDLE_GEMFILE=gemfiles/rails40.gemfile bundle install
BUNDLE_GEMFILE=gemfiles/rails40.gemfile bundle exec rspec spec

To run the tests like Travis:

gem install wwtd
wwtd

APNS providers

By default, we use Houston to deliver push notifications via APNS from the server.

You also need to provide exported versions of your push notification certificate and key as .pem files, these instructions come from the APN on Rails project on how to do that:

Once you have the certificate from Apple for your application, export your key and the apple certificate as p12 files. Here is a quick walkthrough on how to do this:

  1. Click the disclosure arrow next to your certificate in Keychain Access and select the certificate and the key.
  2. Right click and choose Export 2 items….
  3. Choose the p12 format from the drop down and name it cert.p12.

Now covert the p12 file to a pem file:

$ openssl pkcs12 -in cert.p12 -out apple_push_notification.pem -nodes -clcerts

notify_user will look for your pem files within "#{Rails.root}/config/keys/, named development_push.pem and production_push, for the development and production APNS gateways respectively.

The Device model

When delivering via Houston, we also need access to a model which has access to device tokens that is related to your notification target. i.e. Assuming your notification target is a User:

class User < ActiveRecord::Base
  has_many :devices
end

class Device < ActiveRecord::Base
  belongs_to :user

  validates :token, presence:true # A string representation of your device's token, the only thing need to delivery push notifications.
end

A gem that provides such a model is dre, a mountable Rails engine that lets you flag a model (e.g. User) as a device owner and provides a number of routes to allow device registration.

By default, we assume the relation is named :devices, but this can be passed through when enabling APNS for a notification if you want to use something else:

channel :apns,
  aggregate_per: false,
  device_method: :some_other_method

Web interface

Display a list of notifications for a logged in user

visit /notify_user/notifications

Clicking on a notification gets marked as read and taken to the redirect_logic action (notifications_controller.rb)

def redirect_logic(notification)
    class = notification.params[:type].capitalize.constantize
    object = class.find(@notification.params[:id])
    redirect_to property_url(object)
end

Add line to environment.rb file to configure host url for mail notifications

config.action_mailer.default_url_options = { :host => "http://example.com" }

Subscriptions

Unsubscribing from a notification type, first add it to the notify_user.rb initilizer

# Override the default notification type
config.unsubscribable_notifications = ['NewPostNotification','NewSale']

Users can manage their subscription statuses through the web interface

visit notify_user/notifications/unsubscribe

Unsubscribe link helper - add this to your views/notify_user/layouts/action_mailer.html.erb

<% if is_unsubscribeable? @notification  %>
    <p style="text-align: center;">
        <%= unsubscribe_link(@notification, "Unsubscribe") %>
    </p>
<% end %>

Unsubscribing/Subscribing to a specific group_id or resource

Unsubscribing from a specific group_id eg. specific resource. put /notify_user/notifications/unsubscribe_from_object.json expects

subscription: {type: "NotificationType", group_id: 1, unsubscribe: true|false}

returns response_code 201

Upgrade v0.1.4 to v0.2

Run aggregate_interval generator which generates the migrations to add a sent_time field to notifications

rails generate notify_user:aggr_interval
rake db:migrate

Upgrading to JSON params data type

Run json_update generator which generates the migrations to change the params datatype to json as well as convert the current data to json

rails generate notify_user:json_update
rake db:migrate

Changes

Notification description and aggregates has changed syntax slighly from

@@description = "please override this type description"
@@aggregate_per = 10.minutes

to

self.description = "please override this type description"
self.aggregate_per = 10.minutes