The Urbanairship Gem: Sending Push Notifications with Ruby

at February 6th, 2012

If you’re building an app that sends push notifications, Urban Airship is a service that can save you a lot of headache. They provide a common API for sending notifications to iOS, Android and Blackberry devices, as well as some useful features like notification batching, scheduling, and the ability to tag devices to make sending a notification to a large group of users more manageable.

At Groupon we wrote the urbanairship gem to wrap these API interactions, which you can install with gem install urbanairship.

Registering a device token

Before sending notifications to a device, you have to register it with UA. The simplest way to do this is:

Urbanairship.register_device('DEVICE-TOKEN')

You can also give it an alias and a set of tags.

Urbanairship.register_device('DEVICE-TOKEN',
  :alias => 'user-1234',
  :tags => ['chicago-users']
)

The registration call is idempotent. If you want to change a device’s tags or aliases later, you can resend the registration request. Just note that any attributes that are missing from the request will be removed, so be sure to include every tag and alias that you want to associate with that device token each time you make the registration call.

You can also set a ‘quiet time’ and timezone for each device. Check out the Urban Airship API docs for more options.

Sending a notification

Once your device tokens have been registered, sending simple notifications is easy.

Urbanairship.push({
  :device_tokens => ['DEVICE-TOKEN'],
  :aps => {:alert => 'You have a new message!', :badge => 1}
})

You can also specify tags, aliases, and even scheduled delivery times for your notifications. This code sends a push notification, delayed by one hour, to all the devices you’ve tagged with ‘chicago-users’.

Urbanairship.push({
  :tags => ['chicago-users'],
  :schedule_for => [1.hour.from_now],
  :aps => {:alert => 'Hello Chicago!', :badge => 1}
})

The Urban Airship API docs detail even more options that you can specify.

Batched and broadcast notifications

If your back-end system uses some sort of batch process for generating and sending push notifications to multiple users, you can use Urban Airship’s batch push method to cut down on the number of API requests you need to make.

Urbanairship.batch_push(
  {
    :device_tokens => ['DEVICE-TOKEN'],
    :aps => {:alert => 'Message one', :badge => 1}
  },
  {
    :device_tokens => ['DEVICE-TOKEN-TWO'],
    :aps => {:alert => 'Message two', :badge => 1}
  }
)

You can also send a message to ALL of your app’s registered device tokens with the broadcast push method.

Urbanairship.broadcast_push({
  :aps => {:alert => 'Hello EVERYBODY!', :badge => 1}
})

The feedback API

Sometimes a user will opt-in for push notifications on their device and then later disable them or uninstall your app. In these cases, if you try to send a push notification to that device, it will fail and Apple will register the failure in their feedback API. If you send too many repeat notifications to devices that don’t want to receive them, Apple will send you a warning or even revoke your ability to send push notifications.

Fortunately, Urban Airship steps in to help once again. If they notice you trying to send a notification to a device that can’t receive it, UA will refrain from forwarding that notification along to Apple, sparing you from their wrath. But this is really just a safety measure. They also offer a feedback API which you can use to find tokens that have opted-out. You should poll this API periodically and, for each token that comes back, delete or disable it on your end.

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"
#   }
# ]

This retrieves all devices which rejected a notification in the last 24 hours. We’d then go through our database and mark those tokens as inactive or just get rid of them.

That’s it! With Urban Airship and a few lines of Ruby you can send cross-platform push notifications.\

(Source: The Urbanairship Gem: Sending Push Notifications with Ruby)

No Tags


5 thoughts on “The Urbanairship Gem: Sending Push Notifications with Ruby

  1. When i try to use the feedback api i get no response , only a warning warning: peer certificate won't be verified in this SSL session Any idea why ?

    by Saurabh Wadhwa on May 4, 2012 at 4:58 am
  2. Hey Saurabh, If you're getting an empty response, the most likely explanation is that you just don't have any devices stored in the feedback API yet. They'll only start showing up once you start tying to send notifications to clients which have opted-out of push or uninstalled your app since registering. The warning you can just ignore. Or, here's a good article that explains how to either skip verification or get it working, either of which will remove the warning: http://notetoself.vrensk.com/2008/09/verified-https-in-ruby Joey

    by Joey Schoblaska on May 29, 2012 at 9:03 am
  3. I am implementing ths android push notification through Rails app I am getting this below error Urbanairship (1452ms): [Put /api/device_tokens/aaa9b8e4-682f-4de2-9061-7697713576a9, {}], [400, {"error_code": 40001, "details": {"device_token": ["device_token contains an invalid device token: AAA9B8E4-682F-4DE2-9061-7697713576A9"]}, "error": "Data validation error"}] My code is like this Urbanairship.application_key = 'tX3vxeCMSJ6yTvpGZ9Bw-w' Urbanairship.application_secret = 'jmIogjXyRX6UnXmj3llRZQ' Urbanairship.master_secret = 'TVqtJ9ltTOyh6qBk3Hz8tw' Urbanairship.logger = Rails.logger Urbanairship.request_timeout = 5 # default Urbanairship.register_device 'aaa9b8e4-682f-4de2-9061-7697713576a9' Please guide me to resolve this issue.

    by Soutom on June 19, 2012 at 7:40 am
  4. Hey Soutom, You were getting that error because the UA library was trying to register that token as though it were for an iOS device, not and Android one, and it was getting rejected because the expected format for the two is different. Taking a look at the UA Android docs, I realized that the gem's support for Android had started to lag behind, so I did a little catch-up. You can now set `Urbanairship.provider = :android` in your application to fix the device registration issue, or pass a `:provider => :android` option to the registration method. For more information about Android support in the Urbanairship gem, check out the updated readme on GitHub, and be sure to update your gem to version 2.1.0! Let me know if you have any questions, or if anything still seems broken after updating.

    by Joey Schoblaska on June 24, 2012 at 8:26 pm
  5. What other steps need to be taken to set up the UrbanAirship gem? I ran gem install urbanairship and it said that it was installed. But then when I did: Urbanairship.application_key = ‘tX3vxeCMSJ6yTvpGZ9Bw-w’ Urbanairship.application_secret = ‘jmIogjXyRX6UnXmj3llRZQ’ Urbanairship.master_secret = ‘TVqtJ9ltTOyh6qBk3Hz8tw’ Urbanairship.logger = Rails.logger Urbanairship.request_timeout = 5 # default Urbanairship.register_device ‘aaa9b8e4-682f-4de2-9061-7697713576a9′ I get the following error: undefined method `application_key=' for Urbanairship(Table doesn't exist):Class Do I need to set up a class and define variables in the model?

    by Rory on July 31, 2012 at 4:10 pm

Leave a Reply

Your email address will not be published. Required fields are marked *