Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Library for sending Apple Push Notifications to iOS devices from Ruby
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

APN Client RubyGem


This is a RubyGem that allows sending of Apple Push Notifications to iOS devices (i.e. iPhones, iPads) from Ruby. The main features are:

  • Broadcasting of notifications to a large number of devices in a reliable fashion
  • Dealing with errors (via the enhanced format Apple protocol) when sending notifications

Upgrade note

Please note that in this forked version (1.0.0.footballaddicts) we've changed the syntax for creating messages quite a lot. We've done this in order to separate the expensive part of the message creation (payload serialization) into a separate class, which allows us to reuse payloads for multiple messages and is an absolutly essential part of sending tens of thousands of messages fast.

We've also added support for an optional, externaly defined, ConnectionPool (basicly an object supporting #push and #pop that's preloaded with a bunch of ApnClient::Connection instances).


Delivering Your Messages

require 'apn_client'

payload =
  :alert => "New version of the app is out. Get it now in the app store!",
  :badge => 2
message1 ="7b7b8de5888bb742ba744a2a5c8e52c6481d1deeecc283e830533b7c6bf1d099", payload, :message_id => 1)
message2 ="6a5d8de123923912ba744a2a238203aef82d1d98eac283e830533b7c6bf1a100", payload, :message_id => 2)
message3 ="6a5g4de5888bb742ba744a2a5c8e52c6481d1deeecc283e830533b7c6bf1d044", => "New version of the app is out. Get it now in the app store!", :badge => 1),
  :expires_at => ( + 24*60*60)
delivery =[message1, message2, message3],
  :callbacks => {
    :on_write => lambda { |d, m| puts "Wrote message #{m}" },
    :on_exception => lambda { |d, e| puts "Exception #{e} raised when delivering message #{m}" },
    :on_failure => lambda { |d, m| puts "Skipping failed message #{m}" },
    :on_error => lambda { |d, message_id, error_code| puts "Received error code #{error_code} from Apple for message #{message_id}" }
  :consecutive_failure_limit => 10, # If more than 10 devices in a row fail, we abort the whole delivery
  :exception_limit => 3, # If a device raises an exception three times in a row we fail/skip the device and move on
  :connection_config => {
    :host => '', # For sandbox, use:
    :cert =>"my_apn_certificate.pem"),
    :cert_pass => ''
puts "Delivered successfully to #{delivery.success_count} out of #{delivery.total_count} devices in #{delivery.elapsed} seconds"

Checking for Feedback



The payload of an APN message is a JSON formated hash (containing alert message, badge count, content available etc.) and therefore a JSON library needs to be present. We're depending on "yajl-ruby" to encode our JSON.

The gem is tested on MRI 1.9.2.


Football Addicts has made major changes to this fork of the gem.

This gem is an extraction of production code at Mag+ and both Dennis Rogenius and Lennart Friden made important contributions along the way.

The APN connection code has its origins in the APN on Rails gem.


This library is released under the MIT license.


Something went wrong with that request. Please try again.