C2dm on Rails (Android Cloud to Device Messaging on Rails)

C2dm on Rails is a Ruby on Rails gem that allows you to easily add Android Cloud to Device Messaging (push notification)
(Android 2.2> devices) to your Rails application.

Acknowledgements:

This gem is under construction and is forked from our project. The developer
has some allocated hours for developing the gem further.

This gem is a re-write of a apn_on_rails gem that was written by Mark Bates and
before he made it a gem, it was started by Fabien Penso and Sam Soffes. The gem
installation, migration generation and usage is copied from the original apn_on_rails
gem. This is also my first rubygem, so please feel free to fix some oditties and please
comment also.

Requirements:

First it is necessary to sign up to Android Cloud to Device Messaging service.
You need a role account email, it’s password and the name of your Android app for
configuring the c2dm gem.

Sign up here:

http://code.google.com/android/c2dm/signup.html

Installing:

Add the following line to your Gemfile:

   gem 'c2dm_on_rails'

Setup and Configuration:

You need to add the following to your Rakefile so you can use the
Rake tasks that ship with C2dm on Rails:

  begin
    require 'c2dm_on_rails_tasks'
  rescue MissingSourceFile => e
    puts e.message
  end

Now, to create the tables you need for C2dm on Rails, run the following task:

  $ rails generate c2dm_migrations

C2dm on Rails uses the Configatron gem, http://github.com/markbates/configatron/tree/master,
to configure itself. C2dm on Rails uses also the gdata gem for connecting a Google account. The following is an example of an initializer script to
be run to configure the gem (you could put it in config/initializers/c2dm_on_rails.rb):

  configatron.c2dm.api_url = 'https://android.apis.google.com/c2dm/send'
  configatron.c2dm.username = 'your_user_name'
  configatron.c2dm.password = 'password_for_the account'
  configatron.c2dm.app_name = 'your_application_name'

That’s it, now you’re ready to start creating notifications.

Upgrade Notes:

If you are upgrading to a new version of C2dm on Rails you should always run:

  $ rails generate c2dm_migrations

That way you ensure you have the latest version of the database tables needed.

Example:

More information about C2dm services should be read from http://code.google.com/android/c2dm/

  $ ./script/console
  >> device = C2dm::Device.create(:registration_id => "XXXXXXXXXXXXXXXXXXXXXX")
  >> notification = C2dm::Notification.new
  >> notification.device = device
  >> notification.collapse_key = "private_message"
  >> notification.delay_while_idle = true
  >> notification.data = {"sender_id" => "420", "message_text" => "Wanna go for a ride?"}
  >> notification.save

You can use the following Rake task to deliver your notifications:

  $ rake c2dm: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 login with the provided
login data and send notifications using HTTP POST to Google. The client can get an error from Google. There are
several possibilities:

code 200
	Error: QuotaExceeded. It will cancel the notification sending and user should try to send them again after a while.
	Error: DeviceQuotaExceeded. It will cancel the notification sending for the current device and continue from the other devices.
	Error: InvalidRegistration. The devices registration_id is missing or invalid. The device and all its notifications will be deleted.
	Error: NotRegistred. The registration_id is no longer valid. The device and all its notifications will be deleted.
	Error: MessageTooBig. The maximum size of a c2dm push notification is 1024 bytes. User should reduce the size and try again.
	Error: MissingCollapseKey. Google uses a property called collapse_key to collapse a group of like messages when the device is online, so that only the last message is sent to the client. It is required.

code 503
	The server is currently unavailable. The sending process is stopped and sender must retry later. Senders that retry too often and too fast risk being blacklisted.

code 401
	The ClientLogin auth is invalid. Check the config file.

Released under the MIT license.