Pling

Pling is a notification framework that supports multiple gateways. This gem implements the basic framework as well as a gateway to Google's Cloud to Device Messaging Service (C2DM) and Apple's Push Notification Service (APN).

See the API Documentation for more in depth documentation.

This gem has two runtime dependencies

• faraday ~> 0.7
• json ~> 1.4

On JRuby it also requires the jruby-openssl gem.

Add this line to your Gemfile:

gem 'pling'

The configuration is pretty simple. Just add a configuration block like this to your code:

Pling.configure do |config|
  config.gateways.use Pling::C2DM::Gateway, :email => 'your-email@gmail.com', :password => 'your-password', :source => 'your-app-name'
  config.gateways.use Pling::APN::Gateway, :certificate => '/path/to/certificate.pem'

  # config.middleware.use Your::Custom::Middleware, :your => :custom, :configuration => true

  # config.adapter = Your::Custom::Adapter.new
end

After configuring Pling you can send messages to devices by like this:

message = Pling::Message.new("Hello from pling!")
device  = Pling::Device.new(:identifier => 'XXXXXXXXXX...XXXXXX', :type => :iphone)
device.deliver(message)

# ... or call Pling.deliver
Pling.deliver(message, device)

Pling has three core components:

• A device describes a concrete receiver such as a smartphone or an email address.
• A message wraps the content delivered to a device.
• A gateway handles the communication with the service provider used to deliver the message.

You can easily integrate pling into your existing application by implementing #to_pling_device on your device models and #to_pling_message on your message models. Use these methods to either convert your models into Pling::Device and Pling::Message objects or return self and make sure your models implement the basic Pling::Device and Pling::Message interfaces.

Devices store an identifier and a type.

Example:

email_device  = Pling::Device.new(:identifier => 'someone@example.com', :type => :email)
iphone_device = Pling::Device.new(:identifier => 'XXXXXXXXXX...XXXXXX', :type => :iphone)

The Message stores the content as well as additional options that may be evaluated by the gateways.

Example:

options = {} # To be added
message = Pling::Message.new("Hello from Pling", options)

The Gateway delivers the message in the required format to the service provider.

Currently there are these gateways available:

• Android C2DM
• Apple Push Notification
• SMS via Mobilant (See pling-mobilant gem)
• Email (See pling-actionmailer gem)

See the API documentation for details on the available gateways.

Pling has support for middlewares. Currently pling itself does not provide any middlewares but you can easily implement your own. All you need is a class that responds to #deliver(message, device) which yields to call the next middleware on the stack. You might just want to subclass Pling::Middleware::Base to get a simple configuration management.

class Pling::Middleware::TimeFilter < Pling::Middleware::Base
  def deliver(message, device)
    yield(message, device) if configuration[:range].include? Time.now.hour
  end

  protected

    def default_configuration
      super.merge({
        :range => 8..22
      })
    end
end

You can either add middlewares for all gateways or for specific gateways:

Pling.configure do |config|
  config.gateways.use Pling::APN::Gateway, {
    :certificate => '/path/to/certificate.pem',
    :middlewares => [
      [Pling::Middleware::TimeFilter, { :range => 9..17 }] # Don't deliver any messages to iOS devices between 9am and 5pm
    ]
  }

  # Don't deliver any messages between 8am and 10pm
  config.middleware.use Pling::Middleware::TimeFilter
end

Pling supports different adapters. A adapter is in a way similar to a middleware but is responsible for dispatching a device and a message to a gateway. The default adapter simply looks up the first matching gateway for the given device and calls its #deliver(message, device) method. Adapters are handy when you want to add support for background queues. Have a look at this example of an adapter for Resque.

Pling is on Travis running the specs on Ruby 1.8.7, Ruby Enterprise Edition, Ruby 1.9.2, Ruby HEAD, JRuby, Rubinius and Rubinius 2.

See the issue tracker on GitHub.

See the repository on GitHub and feel free to fork it!

See a list of all contributors on GitHub. Thanks a lot everyone!

Copyright (c) 2010-2011 flinc GmbH. See LICENSE for details.