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
gem install urbanairship-ruby
Then require urbanairship
in your code
require 'urbanairship'
or add to Gemfile
gem 'urbanairship-ruby', require: 'urbanairship'
Urbanairship.application_key = 'application-key'
Urbanairship.application_secret = 'application-secret'
Urbanairship.master_secret = 'master-secret'
Urbanairship.logger = Rails.logger
Urbanairship.request_timeout = 5 # default
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']
)
Urbanairship.unregister_device('DEVICE-TOKEN')
Urbanairship.device_info('DEVICE-TOKEN')
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",
# ]
# }
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)
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"
# }
# ]
Urbanairship.schedules
Urbanairship.schedule('03ab5ba1-6f8d-415d-baae-5a81cc24fae2')
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"
# ]
# }
# ]
# }
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)
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")
Urbanairship.create_segment({
:display_name => 'segment1',
:criteria => {:and => [{:tag => 'one'}, {:tag => 'two'}]}
}) # => {}
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
# }
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'}]}
}) # => {}
Urbanairship.delete_segment("abcd-efgh-ijkl") # => {}
Urbanairship.device_tokens # =>
# {
# "device_tokens" => {"device_token"=>"<token>", "active"=>true, "alias"=>"<alias>", "tags"=>[]},
# "device_tokens_count" => 3,
# "active_device_tokens_count" => 1
# }
Urbanairship.device_tokens_count # =>
# {
# "device_tokens_count" => 3,
# "active_device_tokens_count" => 1
# }
Urban Airship allows you to create tags and associate them with devices. Then you can easily send a notification to every device matching a certain tag with a single call to the push API.
Tags must be registered before you can use them.
Urbanairship.add_tag('TAG')
Urbanairship.tags
This will remove a tag from your set of registered tags, as well as removing that tag from any devices that are currently using it.
Urbanairship.remove_tag('TAG')
Urbanairship.tags_for_device('DEVICE-TOKEN')
Urbanairship.tag_device(:device_token => 'DEVICE-TOKEN', :tag => 'TAG')
You can also tag a device during device registration.
Urbanairship.register_device('DEVICE-TOKEN', :tags => ['san-francisco-users'])
Urbanairship.untag_device(:device_token => 'DEVICE-TOKEN', :tag => 'TAG')
notification = {
:tags => ['san-francisco-users'],
:aps => {:alert => 'Good morning San Francisco!', :badge => 1}
}
Urbanairship.push(notification)
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\"}"
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.
- 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.