apn_on_rails 0.3.1 → 0.4.0

data/.gitignore

@@ -0,0 +1,16 @@
+*.log
+.DS_Store
+doc
+tmp
+pkg
+*.gem
+*.pid
+coverage
+coverage.data
+build/*
+*.pbxuser
+*.mode1v3
+.svn
+profile
+spec/active_record/test.db
+.bundle

data/.rspec

@@ -0,0 +1,2 @@
+-f d
+--colour

data/.specification

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: apn_on_rails
+version: !ruby/object:Gem::Version 
+  version: 0.3.1
+platform: ruby
+authors: 
+- markbates
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-26 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: configatron
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: "apn_on_rails was developed by: markbates"
+email: mark@markbates.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+files: 
+- lib/apn_on_rails/apn_on_rails.rb
+- lib/apn_on_rails/app/models/apn/base.rb
+- lib/apn_on_rails/app/models/apn/device.rb
+- lib/apn_on_rails/app/models/apn/notification.rb
+- lib/apn_on_rails/libs/connection.rb
+- lib/apn_on_rails/libs/feedback.rb
+- lib/apn_on_rails/tasks/apn.rake
+- lib/apn_on_rails/tasks/db.rake
+- lib/apn_on_rails.rb
+- lib/apn_on_rails_tasks.rb
+- README
+- LICENSE
+- generators/apn_migrations_generator.rb
+- generators/templates/apn_migrations/001_create_apn_devices.rb
+- generators/templates/apn_migrations/002_create_apn_notifications.rb
+- generators/templates/apn_migrations/003_alter_apn_devices.rb
+has_rdoc: true
+homepage: http://www.metabates.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: magrathea
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: apn_on_rails
+test_files: []
+

data/Gemfile

@@ -0,0 +1,18 @@
+source :gemcutter
+gem 'configatron'
+
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem 'sqlite3-ruby'
+  gem "rspec", ">= 2.0.0.beta.19"
+  gem "bundler", ">= 1.0.0.rc.5"
+  gem "jeweler", "~> 1.5.0.pre2"
+  gem "rcov", ">= 0"
+  gem "actionpack", '~> 2.3.8'
+  gem 'activerecord', "~> 2.3.8", :require => 'active_record'
+end

data/Gemfile.lock

@@ -0,0 +1,45 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionpack (2.3.9)
+      activesupport (= 2.3.9)
+      rack (~> 1.1.0)
+    activerecord (2.3.9)
+      activesupport (= 2.3.9)
+    activesupport (2.3.9)
+    configatron (2.6.4)
+      yamler (>= 0.1.0)
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.0.pre3)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rack (1.1.0)
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.0.0.rc)
+      rspec-core (= 2.0.0.rc)
+      rspec-expectations (= 2.0.0.rc)
+      rspec-mocks (= 2.0.0.rc)
+    rspec-core (2.0.0.rc)
+    rspec-expectations (2.0.0.rc)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.0.rc)
+      rspec-core (= 2.0.0.rc)
+      rspec-expectations (= 2.0.0.rc)
+    sqlite3-ruby (1.3.1)
+    yamler (0.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  actionpack (~> 2.3.8)
+  activerecord (~> 2.3.8)
+  bundler (>= 1.0.0.rc.5)
+  configatron
+  jeweler (~> 1.5.0.pre2)
+  rcov
+  rspec (>= 2.0.0.beta.19)
+  sqlite3-ruby

data/README

@@ -1,15 +1,49 @@
 =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.
+support to your Rails application.  
+
+It supports: 
+* Multiple iPhone apps managed from the same Rails application
+* Individual notifications and group notifications
+* Alerts, badges, sounds, and custom properties in notifications
+* Pull notifications
+
+== Feature Descriptions
+
+Multiple iPhone Apps: In previous versions of this gem a single Rails application was set up to 
+manage push notifications for a single iPhone app.  In many cases it is useful to have a single Rails
+app manage push notifications for multiple iPhone apps.  With the addition of an APN::App model, this 
+is now possible.  The certificates are now stored on instances of APN::APP and all devices are associated
+with a particular app.  
+
+Individual and Group Notifications: Previous versions of this gem treated each notification individually
+and did not provide a built-in way to send a broadcast notification to a group of devices.  Group notifications
+are now built into the gem.  A group notification is associated with a group of devices and shares its 
+contents across the entire group of devices.  
+
+Notification Content Areas: Notifications may contain alerts, badges, sounds, and custom properties.
+
+Pull Notifications: This version of the gem supports an alternative notification method that relies
+on pulls from client devices and does not interact with the Apple Push Notification servers.  This feature
+may be used entirely independently of the push notification features.  Pull notifications may be
+created for an app.  A client app can query for the most recent pull notification available since a 
+given date to retrieve any notifications waiting for it.  
 
 ==Acknowledgements:
 
+From Mark Bates: 
+
 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.
 
+From Rebecca Nesson (PRX.org): 
+
+This gem extends the original version that Mark Bates adapted.  His gem did the hard
+work of setting up and handling all communication with the Apple push notification servers.
+
 ==Converting Your Certificate:
 
 Once you have the certificate from Apple for your application, export your key
@@ -23,10 +57,10 @@ Now covert the p12 file to a pem file:
 
   $ openssl pkcs12 -in cert.p12 -out apple_push_notification_production.pem -nodes -clcerts
 
-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.
 
+Store the contents of the certificate files on the app model for the app you want to send notifications to. 
+
 ==Installing:
 
 ===Stable (RubyForge):
@@ -35,7 +69,7 @@ If you are using a development certificate, then change the name to apple_push_n
 
 ===Edge (GitHub):
 
-  $ sudo gem install markbates-apn_on_rails --source=http://gems.github.com
+  $ sudo gem install PRX-apn_on_rails.git --source=http://gems.github.com
 
 ===Rails Gem Management:
 
@@ -45,7 +79,7 @@ If you like to use the built in Rails gem management:
 
 Or, if you like to live on the edge:
 
-  config.gem 'markbates-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
+  config.gem 'PRX-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
 
 ==Setup and Configuration:
 
@@ -70,7 +104,9 @@ Now, to create the tables you need for APN on Rails, run the following task:
   $ ruby script/generate apn_migrations
 
 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
+to configure itself. (With the change to multi-app support, the certifications are stored in the 
+database rather than in the config directory.  These configurations remain for now.) 
+APN on Rails has the following default configurations that you change as you
 see fit:
 
   # development (delivery):
@@ -103,21 +139,27 @@ If you are upgrading to a new version of APN on Rails you should always run:
 
 That way you ensure you have the latest version of the database tables needed.
 
-==Example:
+==Example (assuming you have created an app and stored your keys on it):
 
   $ ./script/console
-  >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX")
+  >> app = APN::App.find(:first)
+  >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX",:app_id => app.id)
   >> notification = APN::Notification.new
   >> notification.device = device
   >> notification.badge = 5
   >> notification.sound = true
   >> notification.alert = "foobar"
+  >> notification.custom_properties = {:link => "http://www.prx.org"}
   >> notification.save
 
-You can use the following Rake task to deliver your notifications:
+You can use the following Rake task to deliver your individual notifications:
 
   $ rake apn:notifications:deliver
 
+And the following task to deliver your group notifications: 
+
+  $ rake apn:group_notifications:deliver
+
 The Rake task will find any unsent notifications in the database. If there aren't any notifications
 it will simply do nothing. If there are notifications waiting to be delivered it will open a single connection
 to Apple and push all the notifications through that one connection. Apple does not like people opening/closing

data/README.textile

@@ -0,0 +1,198 @@
+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.  
+
+It supports: 
+* Multiple iPhone apps managed from the same Rails application
+* Individual notifications and group notifications
+* Alerts, badges, sounds, and custom properties in notifications
+* Pull notifications
+
+h2. Feature Descriptions
+
+Multiple iPhone Apps: In previous versions of this gem a single Rails application was set up to 
+manage push notifications for a single iPhone app.  In many cases it is useful to have a single Rails
+app manage push notifications for multiple iPhone apps.  With the addition of an APN::App model, this 
+is now possible.  The certificates are now stored on instances of APN::APP and all devices are associated
+with a particular app.  
+
+Individual and Group Notifications: Previous versions of this gem treated each notification individually
+and did not provide a built-in way to send a broadcast notification to a group of devices.  Group notifications
+are now built into the gem.  A group notification is associated with a group of devices and shares its 
+contents across the entire group of devices.  
+
+Notification Content Areas: Notifications may contain alerts, badges, sounds, and custom properties.
+
+Pull Notifications: This version of the gem supports an alternative notification method that relies
+on pulls from client devices and does not interact with the Apple Push Notification servers.  This feature
+may be used entirely independently of the push notification features.  Pull notifications may be
+created for an app.  A client app can query for the most recent pull notification available since a 
+given date to retrieve any notifications waiting for it.  
+
+h2. Acknowledgements:
+
+From Mark Bates: 
+
+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.
+
+From Rebecca Nesson (PRX.org): 
+
+This gem extends the original version that Mark Bates adapted.  His gem did the hard
+work of setting up and handling all communication with the Apple push notification servers.
+
+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
+</pre></code>
+
+If you are using a development certificate, then change the name to apple_push_notification_development.pem instead.
+
+Store the contents of the certificate files on the app model for the app you want to send notifications to. 
+
+h2. Installing:
+
+h3. Stable (RubyForge):
+
+<pre><code>
+  $ sudo gem install apn_on_rails
+</pre></code>
+
+h3. Edge (GitHub):
+
+<pre><code>
+  $ sudo gem install PRX-apn_on_rails.git --source=http://gems.github.com
+</pre></code>
+
+h3. Rails Gem Management:
+
+If you like to use the built in Rails gem management:
+
+<pre><code>
+  config.gem 'apn_on_rails'
+</pre></code>
+
+Or, if you like to live on the edge:
+
+<pre><code>
+  config.gem 'PRX-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
+</pre></code>
+
+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'
+</pre></code>
+
+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
+</pre></code>
+
+Now, to create the tables you need for APN on Rails, run the following task:
+
+<pre><code>
+  $ ruby script/generate apn_migrations
+</pre></code>
+
+APN on Rails uses the Configatron gem, http://github.com/markbates/configatron/tree/master, 
+to configure itself. (With the change to multi-app support, the certifications are stored in the 
+database rather than in the config directory.  These configurations remain for now.) 
+APN on Rails has the following default configurations that you change as you
+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 (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')
+</pre></code>
+
+That's it, now you're ready to start creating notifications.
+
+h3. Upgrade Notes:
+
+If you are upgrading to a new version of APN on Rails you should always run:
+
+<pre><code>
+  $ ruby script/generate apn_migrations
+</pre></code>
+
+That way you ensure you have the latest version of the database tables needed.
+(There is an unaddressed problem in which migration 002 was modified in the repo to add the column custom_properties.
+If you installed the gem prior to that change and try to upgrade following this path you will have to add the 
+custom_properties column to the apn_notifications table by hand.)
+
+h2. Example (assuming you have created an app and stored your keys on it):
+
+<pre><code>
+  $ ./script/console
+  >> app = APN::App.find(:first)
+  >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX",:app_id => app.id)
+  >> notification = APN::Notification.new
+  >> notification.device = device
+  >> notification.badge = 5
+  >> notification.sound = true
+  >> notification.alert = "foobar"
+  >> notification.custom_properties = {:link => "http://www.prx.org"}
+  >> notification.save
+</pre></code>
+
+You can use the following Rake task to deliver your individual notifications:
+
+<pre><code>
+  $ rake apn:notifications:deliver
+</pre></code>
+
+And the following task to deliver your group notifications: 
+
+<pre><code>
+  $ rake apn:group_notifications:deliver
+</pre></code>
+
+The Rake task will find any unsent notifications in the database. If there aren't any notifications
+it will simply do nothing. If there are notifications waiting to be delivered it will open a single connection
+to Apple and push all the notifications through that one connection. Apple does not like people opening/closing
+connections constantly, so it's pretty important that you are careful about batching up your notifications so
+Apple doesn't shut you down.
+
+Released under the MIT license.