Pling Travis build status of 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 => '[email protected]', :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 =


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

message ="Hello from pling!")
device  = => 'XXXXXXXXXX...XXXXXX', :type => :iphone)

# ... 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.


email_device  = => '[email protected]', :type => :email)
iphone_device = => 'XXXXXXXXXX...XXXXXX', :type => :iphone)


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


options = {} # To be added
message ="Hello from Pling", options)


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

Currently there are these gateways available:

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?


    def default_configuration
        :range => 8..22

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


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.

Build Status

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.

Known issues

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.