File: README — Documentation for urbanairship_on

URBAN AIRSHIP ON RAILS

Borrowed Liberally from APN on Rails Gem but designed to interface with urbanairship for simplicity, ease of use, and speedy deployment of push notifications uses identical data schema to APN.. perhaps allowing future upgrade to APN

DEPENDENCIES

requires JSON gem AASM

Note: If you use the aasm gem, you may need to install the gem before you ‘config.gem “aasm”’ in your environment.rb or include it in your Gemfile.

HOW TO INSTALL

ruby script/plugin install git://github.com/yonnage/urbanairship_on_rails

HOW TO GENERATE MIGRATIONS

ruby script/generate apn_migrations rake db:migrate

HOW TO CONFIGURE

=====
Create an initializer named urbanairship.rb with the following content
require File.dirname(__FILE__) + '/../../vendor/plugins/urbanairship_on_rails/lib/urbanairship_on_rails/libs/config'
UA::Config::app_key      = 'YOUR_APP_KEY'
UA::Config::app_secret   = 'YOUR_APP_SECRET'
UA::Config::push_secret  = 'YOUR_PUSH_SECRET'  ### CURRENTLY KNOWN AS "Application Master Secret" on Urban Airship
UA::Config::push_host    = 'go.urbanairship.com'
UA::Config::push_port    = '443'

=====
Set up a daily cron job to set inactive devices to "inactive"
  rake apn:feedback or
  script/runner APN:Feedback.create().run

Set up a cron job to push and manage notifications
  rake apn:push or
  script/runner APN::Notification.process_pending

Set up a cron job to push and manage broadcast notifications
  rake apn:broadcast_push or
  script/runner APN::BroadcastNotification.process_pending

Examples of Use

== Create and register a device:

  # Create device:
  ## Requires a unique token. Token format should be: 5gxadhy6 6zmtxfl6 5zpbcxmw ez3w7ksf qscpr55t trknkzap 7yyt45sc g6jrw7qz

  device = APN::Device.find_or_create_by_token(:token => token)

  #Register the device with Urban Airship

  device.register

  # Your device is now registered and ready to receive notifications.

  # Your mobile application should try to register itself each time the application is launched, which is why it's important
  # to do "find_or_create_by_token"

== Create and send a single simple Notification:

  # Basic Options for Notifications:
  # alert - The message the device will receive.
  # badge - The number of badges (red circle with number) on the device.
  # sound - This is the sound heard on the device.  "default" is the standard device notification sound.
  # device - The device to send the notification to.

  n = APN::Notification.create(:alert => "Hello, World", :badge => 1, :sound => "default", :device => device)

  # Now send the notification to the device:

  n.push

== Create and send a single Notification with more options:

  # Adding more options to a notification.
  # sound - You can also use specific sounds for the alert which are already included as part of the mobile app.
  # badge - Urban Airship supports auto increment / decrement of badges.  Pass "+1" or "-1".
  # custom_properties - Extra information you need to pass to the device.

  n = APN::Notification.create(:alert => "Hello, World", :badge => "+1", :device => device, :sound => "alert1.wav", :custom_properties => {:name => "Bobby", :person_id => 7})

  # Now send the notification to the device

  n.push

== Send all pending notifications:

  # Instead of sending each notification as it is created, you can send them all at once.

  APN::Notification.process_pending

  # Or setup a cron rake task:

  rake apn:push

== Broadcast Notifications

  # Send the same notification to all devices.
  # Use this to avoid making multiple connections if you are sending the same message to all devices.

  APN::BroadcastNotification.create(:alert => "Hello, World", :badge => 1, :sound => "default")

  # Push the BroadcastNotification

  APN::BroadcastNotification.process_pending

  == Broadcast Notifications with Device exclusions.

  # You can exclude devices from receiving a broadcast notification.

  n = APN::BroadcastNotification.create(:alert => "Hello, World", :badge => 1, :sound => "default")

  # Exclude any devices that should not receive the above notification.

  n.excluded_devices.create(:broadcast_notification => n, :device => APN::Device.find(1))
  n.excluded_devices.create(:broadcast_notification => n, :device => APN::Device.find(2))
  n.excluded_devices.create(:broadcast_notification => n, :device => APN::Device.find(3))

  # Push the Broadcast Notification:

  n.push

  # -- OR -- Push all pending Broadcast Notifications:

  APN::BroadcastNotification.process_pending

== Feedback for Devices

  # When a device no longer accepts notifications from your application because of reasons such as the application being removed,
  # Urban Airship will stop trying to send notifications to those devices.  You should run the "feedback" task daily to find and
  # mark all inactive devices as such.

  rake apn:feedback

API CALLS and current support level

REGISTRATION

APN::Device.register              => HTTP PUT to /api/device_tokens/<device_token>
APN::Device.read                  => HTTP GET to /api/device_tokens/<device_token>
APN::Device.unregister            => HTTP DELETE to /api/device_tokens/<device_token>

PUSH

APN::Notifcation.push             => HTTP POST to /api/push/

BATCH PUSH

NOT YET SUPPORTED

BROADCAST

APN::BroadcastNotifcation.push    => HTTP POST to /api/push/broadcast/

FEEDBACK SERVICE

APN::Feedback.create().run        => HTTP GET to /api/device_tokens/feedback/?since=<timestamp>

STATISTICS

NOT YET SUPPORTED