Urbanairship is a Ruby library for interacting with the Urban Airship API.

This gem supports Urbanairship API v3 with Ruby 1.8.6 or above. As the official gem from UA requires Ruby 2.0.0 or above, we build this gem for old Ruby versions.

http://docs.urbanairship.com/api/api-v3-migration-guide.html

Installation

gem install urbanairship-ruby

Then require urbanairship in your code

require 'urbanairship'

or add to Gemfile

gem 'urbanairship-ruby', require: 'urbanairship'

Configuration

Urbanairship.application_key = 'application-key'
Urbanairship.application_secret = 'application-secret'
Urbanairship.master_secret = 'master-secret'
Urbanairship.logger = Rails.logger
Urbanairship.request_timeout = 5 # default

Usage

Registering a device token

Urbanairship.register_device('DEVICE-TOKEN')

You can also pass an alias, and a set of tags to device registration.

Urbanairship.register_device('DEVICE-TOKEN',
  :alias => 'user-123',
  :tags => ['san-francisco-users']
)

Unregistering a device token

Urbanairship.unregister_device('DEVICE-TOKEN')

Retrieving Device Info

Urbanairship.device_info('DEVICE-TOKEN')

Sending a push notification

notification = {
  :audience => {
      :ios_channel => "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
  },
  :notification => {
       :alert => "Hello!"
  },
  :device_types => "all"
}

Urbanairship.push(notification) # =>
# {
#     :ok => true,
#     :operation_id => "df6a6b50-9843-0304-d5a5-743f246a4946",
#     :push_ids => [
#         "9d78a53b-b16a-c58f-b78d-181d5e242078",
#     ]
# }

Batching push notification sends

notifications = [
  {
    :audience => {
        :ios_channel => "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    :notification => {
         :alert => "Hello!"
    },
    :device_types => "all"
  },
  {
    :audience => {
        :android_channel => "b8f9b663-0a3b-cf45-587a-be880946e880"
    },
    :notification => {
         :alert => "Hello!"
    },
    :device_types => "all"
  }
]

Urbanairship.batch_push(notifications)

Polling the feedback API

The first time you attempt to send a push notification to a device that has uninstalled your app (or has opted-out of notifications), both Apple and Urban Airship will register that token in their feedback API. Urban Airship will prevent further attempted notification sends to that device, but it's a good practice to periodically poll Urban Airship's feedback API and mark those tokens as inactive in your own system as well.

# find all device tokens deactivated in the past 24 hours
Urbanairship.feedback(24.hours.ago) # =>
# [
#   {
#     "marked_inactive_on"=>"2011-06-03 22:53:23",
#     "alias"=>nil,
#     "device_token"=>"DEVICE-TOKEN-ONE"
#   },
#   {
#     "marked_inactive_on"=>"2011-06-03 22:53:23",
#     "alias"=>nil,
#     "device_token"=>"DEVICE-TOKEN-TWO"
#   }
# ]

Schedule notifications

Listing your schedules

Urbanairship.schedules
Urbanairship.schedule('03ab5ba1-6f8d-415d-baae-5a81cc24fae2')

Creating your schedules

schedule = {
  :name => "Booyah Sports",
  :schedule => {
    :scheduled_time => "2015-08-01T18:45:00Z"
    },
  :push => {
    :audience => {
      :tag => "spoaaaarts"
    },
    :notification => {
      :alert => "Booyah!"
    },
    :device_types => "all"
  }
}

Urbanairship.create_schedule(schedule) # =>
# {
#   "ok" => true,
#   "operation_id" => "cd9d6390-2a12-11e5-a2b8-90e2ba2901f0",
#   "schedule_urls" => [
#     "https://go.urbanairship.com/api/schedules/03ab5ba1-6f8d-415d-baae-5a81cc24fae2"
#   ],
#   "schedule_ids" => [
#     "03ab5ba1-6f8d-415d-baae-5a81cc24fae2"
#   ],
#   "schedules" => [
#     {
#       "url" => "https://go.urbanairship.com/api/schedules/03ab5ba1-6f8d-415d-baae-5a81cc24fae2",
#       "schedule" => {
#         "scheduled_time" => "2015-08-01T18:45:00"
#       },
#       "name" => "Booyah Sports",
#       "push" => {
#         "audience" => {
#           "tag" => "spoaaaarts"
#         },
#         "device_types" => "all",
#         "notification" => {
#           "alert" => "Booyah!"
#         }
#       },
#       "push_ids" => [
#         "a74db2b6-65f0-465f-82d6-4fa25448b642"
#       ]
#     }
#   ]
# }

Modifying your schedules

You can modify an unsent scheduled push if you know its ID

schedule = {
  :name => "Booyah Sports",
  :schedule => {
    :scheduled_time => "2015-08-01T18:45:00Z"
    },
  :push => {
    :audience => {
      :tag => "spoaaaarts"
    },
    :notification => {
      :alert => "Booyah!"
    },
    :device_types => "all"
  }
}

Urbanairship.update_schedule('03ab5ba1-6f8d-415d-baae-5a81cc24fae2', schedule)

Deleting your schedules

If you know the alias or id of a scheduled push notification then you can delete it from Urban Airship's queue and it will not be delivered.

Urbanairship.delete_schedule("123456789")
Urbanairship.delete_schedule(123456789)
Urbanairship.delete_schedule(:alias => "deadbeef")

Segments

Creating a segment

Urbanairship.create_segment({
  :display_name => 'segment1',
  :criteria => {:and => [{:tag => 'one'}, {:tag => 'two'}]}
}) # => {}

Listing your segments

Urbanairship.segments # =>
# {
#   "segments" => [
#     {
#      "id" => "abcd-efgh-ijkl",
#      "display_name" => "segment1",
#      "creation_date" => 1360950614201,
#      "modification_date" => 1360950614201
#     }
#   ]
# }

Urbanairship.segment("abcd-efgh-ijkl") # =>
# {
#  "id" => "abcd-efgh-ijkl",
#  "display_name" => "segment1",
#  "creation_date" => 1360950614201,
#  "modification_date" => 1360950614201
# }

Modifying a segment

Note that you must provide both the display name and criteria when updating a segment, even if you are only changing one or the other.

Urbanairship.update_segment('abcd-efgh-ijkl', {
  :display_name => 'segment1',
  :criteria => {:and => [{:tag => 'asdf'}]}
}) # => {}

Deleting a segment

Urbanairship.delete_segment("abcd-efgh-ijkl") # => {}

Getting your device tokens

Urbanairship.device_tokens # =>
# {
#   "device_tokens" => {"device_token"=>"<token>", "active"=>true, "alias"=>"<alias>", "tags"=>[]},
#   "device_tokens_count" => 3,
#   "active_device_tokens_count" => 1
# }

Getting a count of your device tokens

Urbanairship.device_tokens_count # =>
# {
#   "device_tokens_count" => 3,
#   "active_device_tokens_count" => 1
# }

Using Urbanairship with Android

The Urban Airship API extends a subset of their push API to Android devices. You can read more about what is currently supported here, but as of this writing, only registration, aliases, tags, broadcast, individual push, and batch push are supported.

To use this library with Android devices, you can set the provider configuration option to :android:

Urbanairship.provider = :android

Alternatively, you can pass the :provider => :android option to device registration calls if your app uses Urbanairship to send notifications to both Android and iOS devices.

Urbanairship.register_device("DEVICE-TOKEN", :provider => :android)

Note: all other supported actions use the same API endpoints as iOS, so it is not necessary to specify the provider as :android when calling them.

Note: all public library methods will return either an array or a hash, depending on the response from the Urban Airship API. In addition, you can inspect these objects to find out if they were successful or not, and what the http response code from Urban Airship was.

response = Urbanairship.push(payload)
response.success? # => true
response.code # => '200'
response.inspect # => "{\"scheduled_notifications\"=>[\"https://go.urbanairship.com/api/push/scheduled/123456\"]}"

If the call to Urban Airship times out, you'll get a response object with a '503' code.

response = Urbanairship.feedback(1.year.ago)
response.success? # => false
response.code # => '503'
response.inspect # => "{\"error\"=>\"Request timeout\"}"

Instantiating an Urbanairship::Client

Anything you can do directly with the Urbanairship module, you can also do with a Client.

client = Urbanairship::Client.new
client.application_key = 'application-key'
client.application_secret = 'application-secret'
client.register_device('DEVICE-TOKEN')

This can be used to use clients for different Urbanairship applications in a thread-safe manner.

Contributing to urbanairship-ruby

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

urbanairship-ruby

Development

Runtime