APND (Apple Push Notification Daemon) is a ruby library to send Apple Push Notifications to iPhones.
Apple recommends application developers create one connection to their upstream push notification server, rather than creating one per notification.
APND acts as an intermediary between your application and Apple (see APND Daemon below). Your application's notifications are queued to APND, which are then sent to Apple over a single connection.
Within ruby applications, APND::Notification can be used to send
notifications to a running APND instance (see APND Notification below) or
directly to Apple. The command line can be used to send single notifications
for testing purposes (see APND Client below).
APND receives push notifications from your application and relays them to
Apple over a single connection as explained above. The apnd command line
utility is used to start APND.
Usage:
apnd daemon [OPTIONS] --apple-cert </path/to/cert>
Required Arguments:
--apple-cert [PATH] PATH to APN certificate from Apple
Optional Arguments:
--apple-host [HOST] Connect to Apple at HOST (default is gateway.sandbox.push.apple.com)
--apple-port [PORT] Connect to Apple on PORT (default is 2195)
--apple-cert-pass [PASSWORD] PASSWORD for APN certificate from Apple
--daemon-port [PORT] Run APND on PORT (default is 22195)
--daemon-bind [ADDRESS] Bind APND to ADDRESS (default is 0.0.0.0)
--daemon-log-file [PATH] PATH to APND log file (default is /var/log/apnd.log)
--daemon-timer [SECONDS] Set APND queue refresh time to SECONDS (default is 30)
--foreground Run APND in foreground without daemonizing
Help:
--help Show this message
APND includes a command line client which can be used to send notifications to
a running APND instance. It is only recommended to send notifications via
apnd push for testing purposes.
Usage:
apnd push [OPTIONS] --token <token>
Required Arguments:
--token [TOKEN] Set Notification's iPhone token to TOKEN
Optional Arguments:
--alert [MESSAGE] Set Notification's alert to MESSAGE
--sound [SOUND] Set Notification's sound to SOUND
--badge [NUMBER] Set Notification's badge number to NUMBER
--custom [JSON] Set Notification's custom data to JSON
--host [HOST] Send Notification to HOST, usually the one running APND (default is 'localhost')
--port [PORT] Send Notification on PORT (default is 22195)
Help:
--help Show this message
The APND::Notification class can be used within your application to send
push notifications to APND.
require 'apnd'
# Set the host/port APND is running on
# (not needed if you're using localhost:22195)
# Put this in config/initializers/apnd.rb for Rails
APND::Notification.upstream_host = 'localhost'
APND::Notification.upstream_port = 22195
# Initialize some notifications
notification1 = APND::Notification.new(
:alert => 'Alert!',
:token => 'fe15a27d5df3c34778defb1f4f3880265cc52c0c047682223be59fb68500a9a2',
:badge => 1
)
notification2 = APND::Notification.new(
:alert => 'Red Alert!',
:token => 'fe15a27d5df3c34778defb1f4f3880265cc52c0c047682223be59fb68500a9a2',
:badge => 99
)
# Send multiple notifications at once to avoid overhead in
# opening/closing the upstream socket connection each time
#
# *IMPORTANT!* Use sock.puts as it appends a new line. If you don't,
# you'll only receive the first notification.
APND::Notification.open_upstream_socket do |sock|
sock.puts(notification1.to_bytes)
sock.puts(notification2.to_bytes)
end
# Send a notification to the upstream socket immediately
notification3 = APND::Notification.create(
:alert => 'Alert!',
:token => 'fe15a27d5df3c34778defb1f4f3880265cc52c0c047682223be59fb68500a9a2',
:badge => 0
)
Apple Push Notification Service keeps a log when you attempt to deliver a notification to a device that has removed your application. A Feedback Service is provided which applications should periodically check to remove from their databases.
The APND::Feedback class can be used within your application to retrieve
a list of device tokens that you are sending notifications to but have
removed your application.
APND::Feedback.upstream_host = 'feedback.push.apple.com'
APND::Feedback.upstream_port = 2196
# Block form
APND::Feedback.find_stale_devices do |token, removed_at|
device = YourApp::Device.find_by_token(token)
unless device.registered_at > removed_at
device.push_enabled = 0
device.save
end
end
# Array form
stale = APND::Feedback.find_stale_devices
stale.each do |(token, removed_at)|
device = YourApp::Device.find_by_token(token)
unless device.registered_at > removed_at
device.push_enabled = 0
device.save
end
end
By default, the APND daemon uses an in-memory queue to collect notifications until it tries to send them Apple. In the event that the daemon crashes, anything in the queue is lost.
You can add persistence, using MongoDB and MongoMapper simply by requiring apnd-persistence rather than apnd, e.g.
require 'apnd-persistence'
Done! See Requirements.
You must have a valid Apple Push Notification Certificate for your iPhone application. Obtain your APN certificate from the iPhone Provisioning Portal at developer.apple.com.
For persistence, you will also need:
- MongoDB
- MongoMapper
and everything those pull in.
Ruby must be compiled with OpenSSL support.
Tests use Shoulda, and optionally TURN.
RubyGems:
gem install apnd
Git:
git clone git://github.com/itspriddle/apnd.git
APND is based on apnserver and apn_on_rails. Either worked just how I wanted, so I rolled my own using theirs as starting points. If APND doesn't suit you, check them out instead.
- Mark Wotton (mwotton)
Copyright (c) 2010-2011 Joshua Priddle. See LICENSE for details.