Permalink
Browse files

Finished documentation.

  • Loading branch information...
markbates committed Jul 24, 2009
1 parent 525710c commit 8fc4bf8b9620a20ad74898cbe5677c70d6639550
View
75 README
@@ -1,16 +1,17 @@
-APN on Rails
-(Apple Push Notifications on Rails)
-=====================
+=APN on Rails (Apple Push Notifications on Rails)
+
+APN on Rails is a Ruby on Rails gem that allows you to easily add Apple Push Notification (iPhone)
+support to your Rails application.
+
+==Acknowledgements:
-Acknowledgements
-----------------
This gem is a re-write of a plugin that was written by Fabien Penso and Sam Soffes.
Their plugin was a great start, but it just didn't quite reach the level I hoped it would.
I've re-written, as a gem, added a ton of tests, and I would like to think that I made it
a little nicer and easier to use.
-Converting Your Certificate
----------------------------
+==Converting Your Certificate:
+
Once you have the certificate from Apple for your application, export your key
and the apple certificate as p12 files. Here is a quick walkthrough on how to do this:
@@ -26,35 +27,46 @@ Put 'apple_push_notification_production.pem' in config/
If you are using a development certificate, then change the name to apple_push_notification_development.pem instead.
-Installing
-----------
+==Installing:
+
+===Stable (RubyForge):
-From RubyForge:
$ sudo gem install apn_on_rails
-Or, if you like to live on the edge:
+===Edge (GitHub):
+
$ sudo gem install markbates-apn_on_rails --source=http://gems.github.com
-
-Then you just add the following require, wherever it makes sense to you:
- require 'apn_on_rails'
+
+===Rails Gem Management:
If you like to use the built in Rails gem management:
+
config.gem 'apn_on_rails'
Or, if you like to live on the edge:
+
config.gem 'markbates-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
-
-Setup and Configuration
------------------------
-Once you have the gem installed you need to add the following to your Rakefile so you can use the
+
+==Setup and Configuration:
+
+Once you have the gem installed via your favorite gem installation, you need to require it so you can
+start to use it:
+
+Add the following require, wherever it makes sense to you:
+
+ require 'apn_on_rails'
+
+You also need to add the following to your Rakefile so you can use the
Rake tasks that ship with APN on Rails:
+
begin
require 'apn_on_rails_tasks'
rescue MissingSourceFile => e
puts e.message
end
Now, to create the tables you need for APN on Rails, run the following task:
+
$ rake apn:db:migrate
APN on Rails uses the Configatron gem, http://github.com/markbates/configatron/tree/master,
@@ -72,17 +84,20 @@ see fit:
That's it, now you're ready to start creating notifications.
-Example
--------
-
- $ ./script/console
- >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX")
- >> notification = APN::Notification.new
- >> notification.device = device
- >> notification.badge = 5
- >> notification.sound = true
- >> notification.alert = "foobar"
- >> notification.save
- >> APN::Notification.send_notifications
+==Example:
+
+ $ ./script/console
+ >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX")
+ >> notification = APN::Notification.new
+ >> notification.device = device
+ >> notification.badge = 5
+ >> notification.sound = true
+ >> notification.alert = "foobar"
+ >> notification.save
+ >> APN::Notification.send_notifications
+
+You can also run the following Rake task to send your notifications:
+
+ $ rake apn:notifications:deliver
Released under the MIT license.
View
@@ -0,0 +1,116 @@
+h1. APN on Rails (Apple Push Notifications on Rails)
+
+APN on Rails is a Ruby on Rails gem that allows you to easily add Apple Push Notification (iPhone)
+support to your Rails application.
+
+h2. Acknowledgements:
+
+This gem is a re-write of a plugin that was written by Fabien Penso and Sam Soffes.
+Their plugin was a great start, but it just didn't quite reach the level I hoped it would.
+I've re-written, as a gem, added a ton of tests, and I would like to think that I made it
+a little nicer and easier to use.
+
+h2. Converting Your Certificate:
+
+Once you have the certificate from Apple for your application, export your key
+and the apple certificate as p12 files. Here is a quick walkthrough on how to do this:
+
+1. Click the disclosure arrow next to your certificate in Keychain Access and select the certificate and the key.
+2. Right click and choose `Export 2 items...`.
+3. Choose the p12 format from the drop down and name it `cert.p12`.
+
+Now covert the p12 file to a pem file:
+<pre><code>
+ $ openssl pkcs12 -in cert.p12 -out apple_push_notification_production.pem -nodes -clcerts
+</code></pre>
+
+Put 'apple_push_notification_production.pem' in config/
+
+If you are using a development certificate, then change the name to apple_push_notification_development.pem instead.
+
+h2. Installing:
+
+h3. Stable (RubyForge):
+<pre><code>
+ $ sudo gem install apn_on_rails
+</code></pre>
+
+h3. Edge (GitHub):
+<pre><code>
+ $ sudo gem install markbates-apn_on_rails --source=http://gems.github.com
+</code></pre>
+
+h3. Rails Gem Management:
+
+If you like to use the built in Rails gem management:
+<pre><code>
+ config.gem 'apn_on_rails'
+</code></pre>
+
+Or, if you like to live on the edge:
+<pre><code>
+ config.gem 'markbates-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
+</code></pre>
+
+h2. Setup and Configuration:
+
+Once you have the gem installed via your favorite gem installation, you need to require it so you can
+start to use it:
+
+Add the following require, wherever it makes sense to you:
+<pre><code>
+ require 'apn_on_rails'
+</code></pre>
+
+You also need to add the following to your Rakefile so you can use the
+Rake tasks that ship with APN on Rails:
+<pre><code>
+ begin
+ require 'apn_on_rails_tasks'
+ rescue MissingSourceFile => e
+ puts e.message
+ end
+</code></pre>
+
+Now, to create the tables you need for APN on Rails, run the following task:
+<pre><code>
+ $ rake apn:db:migrate
+</code></pre>
+
+APN on Rails uses the Configatron gem, http://github.com/markbates/configatron/tree/master,
+to configure itself. APN on Rails has the following default configurations that you change as you
+see fit:
+
+<pre><code>
+ configatron.apn.passphrase # => ''
+ configatron.apn.port # => 2195
+ configatron.apn.host # => 'gateway.sandbox.push.apple.com'
+ configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
+
+ # production:
+ configatron.apn.host # => 'gateway.push.apple.com'
+ configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
+</code></pre>
+
+That's it, now you're ready to start creating notifications.
+
+h2. Example:
+
+<pre><code>
+ $ ./script/console
+ >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX")
+ >> notification = APN::Notification.new
+ >> notification.device = device
+ >> notification.badge = 5
+ >> notification.sound = true
+ >> notification.alert = "foobar"
+ >> notification.save
+ >> APN::Notification.send_notifications
+</code></pre>
+
+You can also run the following Rake task to send your notifications:
+<pre><code>
+ $ rake apn:notifications:deliver
+</code></pre>
+
+Released under the MIT license.
View
@@ -4,7 +4,7 @@ require 'gemstub'
Gemstub.test_framework = :rspec
Gemstub.gem_spec do |s|
- s.version = "0.1.0"
+ s.version = "0.1.1"
s.rubyforge_project = "magrathea"
s.add_dependency('configatron')
end
View
@@ -2,7 +2,7 @@
Gem::Specification.new do |s|
s.name = %q{apn_on_rails}
- s.version = "0.1.0.20090724114507"
+ s.version = "0.1.1.20090724152309"
s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
s.authors = ["markbates"]
@@ -22,13 +22,14 @@
configatron.apn.set_default(:cert, File.join(rails_root, 'config', 'apple_push_notification_production.pem'))
end
-module APN
+module APN # :nodoc:
- module Errors
+ module Errors # :nodoc:
+ # Raised when a notification message to Apple is longer than 256 bytes.
class ExceededMessageSizeError < StandardError
- def initialize(message)
+ def initialize(message) # :nodoc:
super("The maximum size allowed for a notification payload is 256 bytes: '#{message}'")
end
@@ -1,3 +1,8 @@
+# Represents an iPhone (or other APN enabled device).
+# An APN::Device can have many APN::Notification.
+#
+# Example:
+# Device.create(:token => '5gxadhy6 6zmtxfl6 5zpbcxmw ez3w7ksf qscpr55t trknkzap 7yyt45sc g6jrw7qz')
class APN::Device < ActiveRecord::Base
set_table_name 'apn_devices'
@@ -6,6 +11,8 @@ class APN::Device < ActiveRecord::Base
validates_uniqueness_of :token
validates_format_of :token, :with => /^[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}$/
+ # Stores the token (Apple's device ID) of the iPhone (device).
+ #
# If the token comes in like this:
# '<5gxadhy6 6zmtxfl6 5zpbcxmw ez3w7ksf qscpr55t trknkzap 7yyt45sc g6jrw7qz>'
# Then the '<' and '>' will be stripped off.
@@ -1,3 +1,19 @@
+# Represents the message you wish to send.
+# An APN::Notification belongs to an APN::Device.
+#
+# Example:
+# apn = APN::Notification.new
+# apn.badge = 5
+# apn.sound = 'my_sound.aiff'
+# apn.alert = 'Hello!'
+# apn.device = APN::Device.find(1)
+# apn.save
+#
+# To deliver call the following method:
+# APN::Notification.send_notifications
+#
+# As each APN::Notification is sent the <tt>sent_at</tt> column will be timestamped,
+# so as to not be sent again.
class APN::Notification < ActiveRecord::Base
include ::ActionView::Helpers::TextHelper
extend ::ActionView::Helpers::TextHelper
@@ -6,6 +22,10 @@ class APN::Notification < ActiveRecord::Base
belongs_to :device, :class_name => 'APN::Device'
+ # Stores the text alert message you want to send to the device.
+ #
+ # If the message is over 150 characters long it will get truncated
+ # to 150 characters with a <tt>...</tt>
def alert=(message)
if !message.blank? && message.size > 150
message = truncate(message, :length => 150)
@@ -55,6 +75,15 @@ def message_for_sending
class << self
+ # Opens a connection to the Apple APN server and attempts to batch deliver
+ # an Array of notifications.
+ #
+ # This method expects an Array of APN::Notifications. If no parameter is passed
+ # in then it will use the following:
+ # APN::Notification.all(:conditions => {:sent_at => nil})
+ #
+ # As each APN::Notification is sent the <tt>sent_at</tt> column will be timestamped,
+ # so as to not be sent again.
def send_notifications(notifications = APN::Notification.all(:conditions => {:sent_at => nil}))
unless notifications.nil? || notifications.empty?
logger.info "APN: Attempting to deliver #{pluralize(notifications.size, 'notification')}."
@@ -1,4 +1,4 @@
-class CreateApnDevices < ActiveRecord::Migration
+class CreateApnDevices < ActiveRecord::Migratio # :nodoc:
def self.up
create_table :apn_devices do |t|
t.text :token, :size => 71, :null => false
@@ -1,4 +1,4 @@
-class CreateApnNotifications < ActiveRecord::Migration
+class CreateApnNotifications < ActiveRecord::Migration # :nodoc:
def self.up

0 comments on commit 8fc4bf8

Please sign in to comment.