Urban Airship

This add-on is operated by Urban Airship

Deliver customer- and location-targeted cross platform push messages.

Urban Airship

Last Updated: 13 March 2014

This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.

This add-on have been deprecated, and is now disabled for new installs

Table of Contents

Urban Airship is an add-on that powers push notifications to smartphone, tablet and desktop applications. Urban Airship is a cloud service that allows app publishers to send notifications to their users’ apps over the data network. Urban Airship supports notification delivery, user segmentation and integration with customer databases. Additionally, Urban Airship manages end user opt-in status and provides a number of premium usage reporting tools related to mobile engagement and marketing campaign efficacy.

Urban Airship provides client libraries and APIs for many mobile and desktop platforms, including but not limited to iOS, Android, Windows 8, Windows Phone 8, Blackberry, and Phonegap.

Provisioning the add-on

Urban Airship can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add urbanairship
-----> Adding urbanairship to sharp-mountain-4005... done, v18 (free)

Once Urban Airship has been added the following variables will be available in the app configuration:

  • URBANAIRSHIP_PROD_APP_KEY: Production application identifier used to configure the client libraries and to identify the app in API requests.
  • URBANAIRSHIP_PROD_SECRET: Production secret used to configure the Urban Airship client library in your mobile device apps (iOS, Android, etc).
  • URBANAIRSHIP_PROD_MASTER_SECRET: Production secret used for most server-side REST API calls, this secret allows deeper API access than the client secret. This should NOT be used to configure your mobile client apps.
  • URBANAIRSHIP_DEV_APP_KEY: Development application identifier used to configure the client libraries and to identify the app in API requests.
  • URBANAIRSHIP_DEV_SECRET: Development secret used to configure the Urban Airship client library in your mobile device apps (iOS, Android, etc). 
  • URBANAIRSHIP_DEV_MASTER_SECRET: Development secret used for most server-side REST API calls, this secret allows deeper API access than the client secret. This should NOT be used to configure your mobile client apps. 

These can be confirmed using the heroku config:get command.

$ heroku config:get URBANAIRSHIP_PROD_APP_KEY
2spxZt-kSZqU9qT8VepmIg

After installing Urban Airship, the Urban Airship client libraries will need to be integrated with your mobile application. If you use the REST APIs to manage your users and push notifications, you will also need to configure your Heroku app with the app_key and master_secret to be able to authenticate with our API.

Core documentation

Urban Airship Technical Documentation

Urban Airship Dashboard User Documentation

The use of Urban Airship client libraries and APIs does not deviate from the standard documentation on Heroku. The information in our core documentation is applicable without alteration for users of the Urban Airship Heroku add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export ADDON_CONFIG_NAME=value.

Use Foreman to reliably configure and run the process formation specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the ADDON_CONFIG_NAME values retrieved from heroku config to .env.

$ heroku config -s | grep URBANAIRSHIP >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Multiple Environments

For the typical Urban Airship customer, we recommend that each mobile app have a “development” and “production” app setup on the Urban Airship system. To understand this, we need to discuss the term “app.”

Disambiguating “App”

The term “App” has many meanings in the Heroku, Urban Airship, and mobile contexts. What Urban Airship describes as an app can actually represent multiple mobile applications. This is a part of the power of the Urban Airship platform: it simplifies the differences between the various push platforms of the various vendors.

For example, if you had a todo list app called 23ToDo, it may have separate code bases for iOS, Android, and Windows Phone 8. However, for the purposes of sending push notifications, it may be useful for those three mobile apps (which are all the same 23ToDo app) to share the same Urban Airship configuration. In this way, a push could be sent to the users of all three mobile apps simultaneously.

For each Heroku app we provision a Production and Development version of the Urban Airship app.

Development versus Production

The typical practice with Urban Airship apps is to create one “production” app and one “development” app per mobile app (mobile app in this case meaning all mobile app builds sharing the same Urban Airship app credentials, per above). The development app sends pushes through the “test” servers of the push notification vendors. The production app pushes through production push servers. This split also serves to segment your test build users from your actual production users, making it easier and less risky to test push messages during development.

On Heroku

Managing Multiple Environments for an App describes a best practice of having two Heroku apps for each logical app: a Staging app and a Production app. Urban Airship would recommend that your Staging app be linked to your “development” app on the Urban Airship side. Likewise, your Heroku Production app would be linked to your “production” Urban Airship app.

We recommend that you provision the Urban Airship addon from your production Heroku app. You will receive the configuration parameters for the Urban Airship production and development apps. In order to port these settings into your staging Heroku app, you can use the following commands:

    heroku config:set URBANAIRSHIP_DEV_APP_KEY=XXX --remote staging
    heroku config:set URBANAIRSHIP_DEV_SECRET=XXX --remote staging
    heroku config:set URBANAIRSHIP_DEV_MASTER_SECRET=XXX --remote staging

This will make these configuration settings available in your staging environment. If necessary you can use the same technique to add the production credentials to your staging environment as well.

Sending a push notification from Ruby

Once you have the Urban Airship client-side libraries included in your client apps, it is time to test out a push! You can do this either from our dashboard (see Dashboard below) or programmatically from your server-side app.

The following is an example of making a POST request to the Urban Airship API server using Ruby.

require 'net/http'
require 'net/https'

require 'rubygems'
require 'json'

uri = URI("https://go.urbanairship.com/api/push/broadcast/")
message = "Hello, I am a push notification!"
payload ={
  "aps" => {
          "message" => message
  },
  "android" => {
    "message" => message
  }
}.to_json

req = Net::HTTP::Post.new(uri.path)
req.content_type = "application/json"
req.basic_auth ENV['URBANAIRSHIP_DEV_APP_KEY'], ENV['URBANAIRSHIP_DEV_MASTER_SECRET']
req.body = payload
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
response = http.request(req)

puts "Response #{response.code} #{response.message}: #{response.body}"

If your client library is installed and security certificates configured correctly on the Urban Airship Dashboard, your app should receive this push. Congrats!

Sending a push notification from Python

The following is an example of making a POST request to the Urban Airship API server using Python.

import os
import json

import requests

"""
Send a push to all users using the Requests library
http://docs.python-requests.org/en/latest/

Auth username/password is the app key and master secret
"""
uri = 'https://go.urbanairship.com/api/push/broadcast/'
auth = (
    os.environ['URBANAIRSHIP_DEV_APP_KEY'],
    os.environ['URBANAIRSHIP_DEV_MASTER_SECRET']
)
message = 'Hello, I am a push notification!'
payload = {
    'aps': {
        'alert': message
    },
    'android': {
        'alert': message
    },
}
response = requests.post(
    uri,
    data=json.dumps(payload),
    auth=auth,
    headers={'content-type': 'application/json'}
)
print "Response ", response.status_code, response.text

Dashboard

For more information on the features available within the Urban Airship dashboard please see the Urban Airship Dashboard Guide.

Urban Airship offers a rich dashboard with WYSIWYG push creation tools, sophisticated segmentation, and in-depth analytics. It also is the easiest way to configure your app, including the credentials you will need to send push messages through the servers of the push messaging providers. The dashboard can be used by developers to configure and test push notification integration in the app. It can also be used by the business and marketing departments to segment, send push notifications, and retrieve push performance reports.

The dashboard can be accessed via the CLI:

$ heroku addons:open urbanairship
Opening urbanairship for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting Urban Airship from the Add-ons menu.

Troubleshooting

Please see our documentation for specific troubleshooting information.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

You may upgrade your Urban Airship plan at any time without fear of service interruption. If you downgrade your plan, be sure that your active user count is lower than the maximum active user limit of the new plan, or service disruption may occur.

Our plans are named simply: tier1, tier2, tier3, tier4, tier5. Please see our plans page for plan benefit information.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade urbanairship:tier3
-----> Upgrading urbanairship:tier3 to sharp-mountain-4005... done, v18 ($999/mo)
       Your plan has been updated to: urbanairship:tier3

Removing the add-on

Urban Airship can be removed via the CLI.

This will deactivate your account. You will no longer be able to send push messages via our service once this action is taken.

$ heroku addons:remove urbanairship
-----> Removing urbanairship from sharp-mountain-4005... done, v20 (free)

Urban Airship apps cannot be re-activated once they have been deactivated. If you later decide to re-enable the Urban Airship addon, you will be assigned new production and development apps. This means you will need to rebuild any mobile client application that has embedded your old Urban Airship app credentials, as well as reconfigure your security and certificate information with the various push providers (Apple, Google, etc). If you have already gone through this process, please consider the above information before deactivating the Urban Airship addon, especially if you plan to re-activate it later.

Support

All Urban Airship support and runtime issues should be submitted via support@urbanairship.com. Please mention that you are a Heroku customer. Any non-support related issues or product feedback is welcome as well.