EventMachine'd Apple Push Notifications
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
certs
lib
script
spec
.gitignore
.rspec
Gemfile
LICENSE
README.md
Rakefile
em-apn.gemspec

README.md

EM-APN - EventMachine'd Apple Push Notifications

We want:

  • Streamlined for a persistent connection use-case
  • Support for the enhanced protocol, with receipts

Usage

In a nutshell:

require "em-apn"

# Inside a reactor...
notification = EM::APN::Notification.new(token, :alert => alert)
client = EM::APN::Client.connect
client.deliver(notification)

Using this interface, the easiest way to configure the connection is by setting some environment variables so that EM::APN can find your SSL certificates:

ENV["APN_KEY"]  = "/path/to/key.pem"
ENV["APN_CERT"] = "/path/to/cert.pem"

Also, by default, the library connects to Apple's sandbox push server. If you want to connect to the production server, simply set the APN_ENV environment variable to production:

ENV["APN_ENV"] = "production"

The gateway and SSL certs can also be set directly when instantiating the object:

client = EM::APN::Client.connect(
  :gateway => "some.host",
  :key     => "/path/to/key.pem",
  :cert    => "/path/to/cert.pem"
)

The client manages an underlying EM::Connection, and it will automatically reconnect to the gateway when the connection is closed. Callbacks can be set on the client to handle error responses from the gateway, connection open & close events:

client = EM::APN::Client.connect
client.on_error do |response|
  # See EM::APN::ErrorResponse
end

client.on_close do
  # Do something.
end

client.on_open do
  # Do something
end

In our experience, we've found that Apple immediately closes the connection whenever an error is detected, so the error and close callbacks are nearly always called one-to-one. These methods exist as a convenience, and the callbacks can also be set directly to anything that responds to #call:

client.error_callback = Proc.new { |response| ... }
client.close_callback = Proc.new { ... }
client.open_callback  = Proc.new { ... }

Max Payload Size

Apple enforces a limit of 2048 bytes for the entire payload.

If you attempt to deliver a notification that exceeds that limit, the library will raise an EM::APN::Notification::PayloadTooLarge exception.

To prevent that from happening, you can call #truncate_alert! on the notification.

notification = EM::APN::Notification.new(...)
notification.truncate_alert!
client.deliver(notification)

Inspiration

Much thanks to: