Joey Schoblaska

The Urbanairship Gem: Sending Push Notifications with Ruby

Wed, 04 Jan 2012 11:12:00 -0500

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.

Cory Doctorow: The Coming War on General Computation

Sat, 31 Dec 2011 10:34:12 -0500

Cory Doctorow: The Coming War on General Computation:

The triviality of copyright tells you that when other sectors of the economy start to evince concerns about the internet and the PC, that copyright will be revealed for a minor skirmish, and not a war. Why would other sectors nurse grudges against computers? Well, because the world we live in today is /made/ of computers. We don’t have cars anymore, we have computers we ride in; we don’t have airplanes anymore, we have flying Solaris boxes with a big bucketful of SCADA controllers [laughter]; a 3D printer is not a device, it’s a peripheral, and it only works connected to a computer; a radio is no longer a crystal, it’s a general-purpose computer with a fast ADC and a fast DAC and some software.

…

The grievances that arose from unauthorized copying are trivial, when compared to the calls for action that our new computer-embroidered reality will create

…

Regardless of whether you think these are real problems or merely hysterical fears, they are nevertheless the province of lobbies and interest groups that are far more influential than Hollywood and big content are on their best days, and every one of them will arrive at the same place — “can’t you just make us a general purpose computer that runs all the programs, except the ones that scare and anger us? Can’t you just make us an Internet that transmits any message over any protocol between any two points, unless it upsets us?”

…

As a member of the Walkman generation, I have made peace with the fact that I will require a hearing aid long before I die, and of course, it won’t be a hearing aid, it will be a computer I put in my body. So when I get into a car — a computer I put my body into — with my hearing aid — a computer I put inside my body — I want to know that these technologies are not designed to keep secrets from me, and to prevent me from terminating processes on them that work against my interests.

…

Freedom in the future will require us to have the capacity to monitor our devices and set meaningful policy on them, to examine and terminate the processes that run on them, to maintain them as honest servants to our will, and not as traitors and spies working for criminals, thugs, and control freaks.

Seen in Warsaw.

Wed, 30 Mar 2011 00:00:00 -0400

Seen in Warsaw.

Hold Fast, a Documentary About Anarchy and Sailing

Sat, 06 Nov 2010 00:00:00 -0400

Hold Fast, a Documentary About Anarchy and Sailing

Honoring Dissident Liu Xiaobo: Nobel Prize Is Slap in the Face for China

Tue, 12 Oct 2010 00:00:00 -0400

Honoring Dissident Liu Xiaobo: Nobel Prize Is Slap in the Face for China:

Liu Xiaobo, 54, a literary critic and philosopher, was awarded the Nobel Peace Prize last Friday. He had no idea that he had even been nominated — news of a political nature is taboo in the Jinzhou prison.

"You just need to get started" is bad advice

Tue, 14 Sep 2010 00:00:00 -0400

"You just need to get started" is bad advice:

Notice that MIT’s idea-centric process (e.g., finding the right ideas is key) contrasts with the progress-centric process (e.g., getting started is key) that dominates popular discussion on getting things done.

Strategy's Golden Rule

Wed, 28 Apr 2010 00:00:00 -0400

Strategy's Golden Rule:

What your fiercest rival does badly, do incredibly well.

Less Talk More Rock

Thu, 25 Mar 2010 00:00:00 -0400

Less Talk More Rock:

That’s why Jordan Mechner’s advice — and it’s so beautiful — is to proceed from 1 to 3 to 2. Go right from the inspiration — the vision — to actually making it. Don’t think it through. Don’t talk about it. Don’t plan it. Dive in and start making it happen. If you do that — if you can start rocking — you’ll get some momentum, and when you have some momentum then the project has a chance, because now you’re into it. It’s going somewhere, it’s tangible. Sure, you’ll still run up against problems to solve and decisions to make, but you’ll approach these in the moment and solve them in the moment. You’ll solve them so you can keep moving.

Your High IQ Will Kill Your Startup

Fri, 05 Mar 2010 00:00:00 -0500

Your High IQ Will Kill Your Startup:

Being intelligent is like having a knife. If you train every day in using the knife, you will be invincible. If you think that just having a knife will make you win any battle you fight, then you will fail.

The city walls of Xi’an, one of the four ancient capitals...

Tue, 19 Jan 2010 00:00:00 -0500

The city walls of Xi’an, one of the four ancient capitals of China.

Inside Beijing’s Forbidden City.

Sun, 17 Jan 2010 00:00:00 -0500

Inside Beijing’s Forbidden City.

The Forbidden City.

Fri, 15 Jan 2010 00:00:00 -0500

The Forbidden City.

Thinking Sphinx: Searching By Location And Keyword

Mon, 29 Jun 2009 00:00:00 -0400

Let’s say that we’re building a Rails app to index independent coffee shops in our town. Every coffee shop has a name, a description and some comments, as well as a latitude and longitude value so that we can place it on a map. We want to allow our users to search through the coffee shops in our database by providing keywords and a location. We want our searches to take into account BOTH the relevance of the results based on keyword matches, as well as their proximity to the location given.

Thinking Sphinx

For this tutorial we’ll be using Thinking Sphinx, a great search library for Ruby projects.

First, we’ll need to install Sphinx and Thinking Sphinx. If you’re new to Sphinx, you might want to check out this great tutorial which explains the basics of indexing and searching.

Indexing the Model

Once Sphinx and Thinking Sphinx are installed, we’re ready to define the indexes on our model. This tells Sphinx which fields to store in its index for searching, which attributes we want to have available for sorting and filtering, as well as any other properties we want to define.

# Table name: coffee_shops
#
#  id              :integer(4)      not null, primary key
#  name            :string(255)
#  description     :text
#  lat             :float
#  lng             :float

class CoffeeShop < ActiveRecord::Base
  has_many :comments

  define_index do
    # fields
    indexes :name
    indexes :description
    indexes comments.body, :as => :comments

    # attributes
    has 'RADIANS(lat)', :as => :lat,  :type => :float
    has 'RADIANS(lng)', :as => :lng,  :type => :float

    # properties
    set_property :latitude_attr  => 'lat'
    set_property :longitude_attr => 'lng'
    set_property :field_weights  => { 'name'        => 10,
                                      'description' => 2,
                                      'comments'    => 1 }
  end
end

The fields in the index tell Sphinx that we want our search to look at the name and description of our coffee shops, as well as the body of any comments that have been made. Notice that we’re able to index not only fields that are in our coffee_shops table, but also fields from associated records - in this case the bodies of our comments.

Defining a lat and lng attribute are necessary for doing geography-based searches. The big gotcha here is that Sphinx needs these attributes to be stored as radians, whereas most geocoding APIs (such as Google) use decimal degrees. The SQL ‘RADIANS(lat)’ will automatically do this conversion for you. If you happen to have your lat and lng stored as radians already, however, you can just define your attributes like this:

# attributes
has :lat
has :lng

Finally, we define our properties. The :latitude_attr and :longitude_attr properties tell Sphinx which fields we’re using for our geography calculations. The :field_weights define how much weight we want to give to each indexed field. If we get a match on the name of one of our coffee shops, that should weigh heavier in the relevance than if we got a match on one of our comment bodies.

The Search Method

Next, we’ll redefine the CoffeeShop::search class method, allowing us to use a custom sort expression and a geocode object.

class CoffeeShop < ActiveRecord::Base

  # ...

  METERS_PER_MILE = 1609.344
  SORT_EXPRESSION = "@weight * @weight / @geodist"
  RADIUS = 5

  def self.search(keywords, var = {})
    search_options = {:page => var[:page] || 1, :per_page => PER_PAGE}

    if var[:geocode] && var[:geocode].success?
      lat = (var[:geocode].lat / 180.0) * Math::PI
      lng = (var[:geocode].lng / 180.0) * Math::PI

      search_options[:geo] = [lat, lng]
      search_options[:sort_mode] = :expr
      search_options[:sort_by] = SORT_EXPRESSION
      search_options[:with] = {"@geodist" => 0.0..(RADIUS * METERS_PER_MILE)}
    end

    super(keywords, search_options)
  end
end

That’s a lot of awesome. Let’s walk through our new search class and see what’s going on.

@geodist, @weight and SORT_EXPRESSION

Sphinx gives you some special attributes for sorting and filtering, including @weight and @geodist. @weight is the relevance of a search result (the larger the number, the more relevant the result) and is the default sorting option. @geodist is the distance (in meters) of the search result from the anchor point. By defining SORT_EXPRESSION to use both the @weight and @geodist attributes, we can sort in a way that takes both into account. You can add any other operators and attributes to this expression that you want to tailor how your results are sorted. For instance, if you had a ‘popularity’ attribute on your model and wanted more popular coffee shops to rank better, you could define your search expression as ‘@weight * @weight / @geodist + popularity’ (just make sure you add ‘popularity’ to the list of attributes on your model index).

:page and :per_page

If you have WillPaginate installed, Thinking Sphinx will automatically wrap your search results in a WillPaginate collection, allowing you to use all your normal WillPaginate view helpers. Neat!

:geo, :sort_mode, :sort_by and :with

These attributes affect the sorting and filtering of our search. :geo tells Sphinx that we are doing a geography search with specific lat and lng variables and tells it to add the @geodist attribute to each result. :sort_mode and :sort_by tell Sphinx that we want to sort results by our SORT_EXPRESSION constant. The :with option tells Sphinx that we only want to return results within five miles of our anchor point.

Finally, the last line performs the actual search based on the keywords and search options we’ve set up.

Executing Searches

Now that our model is set up, executing searches is as simple as:

@geocode = MultiGeocoder.geocode(params[:query_location])

@coffee_shops = CoffeeShop.search(params[:query_keywords],
                                  :page => params[:page],
                                  :geocode => @geocode)

This will execute our query with all the parameters we care about and return a paginated collection of coffee shops sorted by relevance and distance. Also, if any or all of the parameters are blank, nothing breaks! If all parameters are blank, a Sphinx search won’t even be performed, and a WillPaginate collection will be returned with our model’s default sorting and PER_PAGE attributes.

Happy searching!

The desert outside the Huacachina Oasis in Peru.

Sun, 15 Jun 2008 00:00:00 -0400

The desert outside the Huacachina Oasis in Peru.

Angkor Wat.

Mon, 28 May 2007 00:00:00 -0400

Angkor Wat.