Finished documentation for feedback integration.

README

@@ -73,14 +73,25 @@ APN on Rails uses the Configatron gem, http://github.com/markbates/configatron/t
 to configure itself. APN on Rails has the following default configurations that you change as you
 see fit:
 
+  # development (delivery):
   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:
+  # production (delivery):
   configatron.apn.host # => 'gateway.push.apple.com'
   configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
+
+  # development (feedback):
+  configatron.apn.feedback.passphrase # => ''
+  configatron.apn.feedback.port # => 2196
+  configatron.apn.feedback.host # => 'feedback.sandbox.push.apple.com'
+  configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
+
+  # production (feedback):
+  configatron.apn.feedback.host # => 'feedback.push.apple.com'
+  configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
 
 That's it, now you're ready to start creating notifications.
 

README.textile

@@ -82,14 +82,25 @@ to configure itself. APN on Rails has the following default configurations that
 see fit:
 
 <pre><code>
+  # development (delivery):
   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:
+  # production (delivery):
   configatron.apn.host # => 'gateway.push.apple.com'
   configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
+
+  # development (feedback):
+  configatron.apn.feedback.passphrase # => ''
+  configatron.apn.feedback.port # => 2196
+  configatron.apn.feedback.host # => 'feedback.sandbox.push.apple.com'
+  configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
+
+  # production (feedback):
+  configatron.apn.feedback.host # => 'feedback.push.apple.com'
+  configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
 </code></pre>
 
 That's it, now you're ready to start creating notifications.

generators/apn_migrations_generator.rb

@@ -1,5 +1,9 @@
 require 'rails_generator'
-# Generates the migrations necessary for APN on Rails
+# Generates the migrations necessary for APN on Rails.
+# This should be run upon install and upgrade of the 
+# APN on Rails gem.
+# 
+#   $ ruby script/generate apn_migrations
 class ApnMigrationsGenerator < Rails::Generator::Base
 
   def manifest # :nodoc:

generators/templates/apn_migrations/003_add_registered_at_to_apn_devices.rb

@@ -1,7 +1,7 @@
 class AddRegisteredAtToApnDevices < ActiveRecord::Migration # :nodoc:
 
-  module APN
-    class Device < ActiveRecord::Base
+  module APN # :nodoc:
+    class Device < ActiveRecord::Base # :nodoc:
       set_table_name 'apn_devices'
     end
   end
@@ -14,6 +14,7 @@ def self.up
       device.save!
     end
 
+    add_index :apn_devices, :token
   end
 
   def self.down

lib/apn_on_rails/app/models/apn/device.rb

@@ -17,6 +17,9 @@ class APN::Device < APN::Base
 
   before_save :set_last_registered_at
 
+  # The <tt>feedback_at</tt> accessor is set when the 
+  # device is marked as potentially disconnected from your
+  # application by Apple.
   attr_accessor :feedback_at
 
   # Stores the token (Apple's device ID) of the iPhone (device).

lib/apn_on_rails/app/models/apn/notification.rb

@@ -82,6 +82,9 @@ class << self
     # 
     # As each APN::Notification is sent the <tt>sent_at</tt> column will be timestamped,
     # so as to not be sent again.
+    # 
+    # This can be run from the following Rake task:
+    #   $ rake apn:notifications:deliver
     def send_notifications(notifications = APN::Notification.all(:conditions => {:sent_at => nil}))
       unless notifications.nil? || notifications.empty?
 

lib/apn_on_rails/libs/connection.rb

@@ -33,35 +33,12 @@ def open_for_delivery(options = {}, &block)
       #   configatron.apn.feedback.host = 'feedback.push.apple.com' # Production
       #   configatron.apn.feedback.cert = File.join(rails_root, 'config', 'apple_push_notification_development.pem')) # Development
       #   configatron.apn.feedback.cert = File.join(rails_root, 'config', 'apple_push_notification_production.pem')) # Production
-      def open_for_feedback(options = {}, &block) # :nodoc:
+      def open_for_feedback(options = {}, &block)
         options = {:cert => configatron.apn.feedback.cert,
                    :passphrase => configatron.apn.feedback.passphrase,
                    :host => configatron.apn.feedback.host,
                    :port => configatron.apn.feedback.port}.merge(options)
         open(options, &block)
-
-        # 'c5280d58a5dda773f5d59578f895c0e16124fab77938ac00b903115a21d4'.unpack('N1n1H140')
-        # time (big endian), token length (big endian), device token (binary)
-        # [1664430648, 12388, "353861356464613737336635643539353738663839356330653136313234666162373739333861633030623930333131356132316434"]
-        # APN::Connection.open_for_feedback do |conn, sock|
-        #   # begin
-        #   #   while data = sock.read(76)
-        #   #     next if data.size < 76
-        #   #     timestamp, token_length, device_token = data.unpack('N1n1H140')
-        #   #     puts timestamp
-        #   #     puts token_length
-        #   #     puts device_token
-        #   #   end
-        #   # rescue SocketError => e
-        #   #   puts 'oops!'
-        #   #   puts e.message
-        #   # end
-        # 
-        #   while line = sock.gets   # Read lines from the socket
-        #     puts line.chop.unpack('N1n1H140')      # And print with platform line terminator
-        #   end
-        # 
-        # end
       end
 
       private

lib/apn_on_rails/libs/feedback.rb

@@ -28,6 +28,16 @@ def devices(&block)
         return devices
       end # devices
 
+      # Retrieves a list of APN::Device instnces from Apple using
+      # the <tt>devices</tt> method. It then checks to see if the
+      # <tt>last_registered_at</tt> date of each APN::Device is
+      # before the date that Apple says the device is no longer
+      # accepting notifications then the device is deleted. Otherwise
+      # it is assumed that the application has been re-installed
+      # and is available for notifications.
+      # 
+      # This can be run from the following Rake task:
+      #   $ rake apn:feedback:process
       def process_devices
         APN::Feedback.devices.each do |device|
           if device.last_registered_at < device.feedback_at