Android Client Library Overview¶
Copyright 2011 Urban Airship, Inc. All Rights Reserved.
Introduction¶
This guide will help you get up to speed on integrating the new Urban Airship client library in your Android app. We’ll start by going over the changes from previous library versions. From there, we’ll cover the basic steps needed to integrate the library, including setting application credentials and enabling Analytics reporting to get the most out of your app deployment.
Javadoc¶
While this guide provides a high level walkthrough of the library, we also provide Javadoc documentation for the API.
Download¶
You can download our latest Android client library distribution here. This zip file contains the library JAR file, as well as Eclipse sample projects with the JAR file already included.
Upgrading from Previous Embedded Push Betas¶
Changes necessary to upgrade from 0.9.1:
- Change CoreReceiver namespace from com.urbanairship.push.embedded to com.urbanairship.push in your AndroidManifest.xml
- Declaring NotificationOpenedReceiver in your AndroidManifest.xml is no longer required
Changes necessary to upgrade from 0.9.0:
- Change EmbeddedPushService to PushService in your AndroidManifest.xml
- PushManager.ACTION_NOTIFICATION_OPENED_BASE should now be PushManager.ACTION_NOTIFICATION_OPENED in your custom IntentReceiver
Changes from previous older of Urban Airship Embedded Push:
- Naming changes:
- Most classes and packages have been re-organized and renamed
- Init changes
- In your application’s onCreate(), call UAirship.takeOff() instead of AirMailEmbedded.init()
- Push is disabled by default to give your app a chance to offer your users an opt-in at first launch. If you want push enabled anyway, simply call PushManager.enablePush(true) after takeOff.
- Customization options are handle differently – see the Customizing sections below
- Manifest changes
- The manifest is very similar to the old version. You’ll need to change the name of the service and the CoreReceiver classes, but you can leave your existing IntentReceiver declaration.
- Many of the intent filters are no longer needed - see the manifest section for details
- IntentRecevier changes
- You can now place this in any package you want, but it must now be specified with a call to UAirship.shared().setIntentReceiver(YourIntentReceiver.class)
- The intent action names and extra names have changed, but they are now constants. See the IntentReceiver section for more details.
- Preferences changes
- Sound/vibrate preferences are now handled through the PushPreferences class. Get an instance by calling PushManager.shared().getPreferences()
Getting Started¶
Adding the Client Library JAR to your Project¶
If you are using Eclipse to develop your project, simply right-click on the top-level project in the Package Explorer pane and choose Properties. Click Java Build Path, Libraries, then Add External Jars. Browse to the urbanairship-lib-<version>.jar file, select it, and then click “OK”.
Otherwise, if you’re using a different IDE, just add a reference to the urbanairship-lib-<version>.jar file in your classpath, and ensure that it is bundled in your final application.
TakeOff¶
Initializing the UrbanAirship library is easy, and only requires two additional lines of code. We’ll be adding a call to UAirship.takeOff in the app’s onCreate methods. Here is a simple example:
import android.app.Application;
import com.urbanairship.UAirship;
public class MyApplication extends Application {
@Override
public void onCreate() {
UAirship.takeOff(this);
}
}
Setting App Credentials¶
Once you’ve added the takeOff call to your application class, you’ll still need to specify your app’s credentials before it can interact with an application you’ve created on the Urban Airship dashboard (https://go.urbanairship.com). The Android client library looks for these in a file called airshipconfig.properties, in the assets subfolder of your Android project directory. There you can set your app’s key and secret, and whether the app is currently in development or production. A well-formed airshipconfig.properties file should look something like the example shown below, replacing strings such as “Your Development App Key” with the appropriate keys for your app, and setting the inProduction boolean accordingly:
developmentAppKey = Your Development App Key
developmentAppSecret = Your Development App Secret
productionAppKey = Your Production App Key
productionAppSecret = Your Production App Secret
inProduction = false
Reporting¶
The Android library provides built-in usage reporting for your application. It will enable you to track time in app (per activity) and the results of push notifications. The only thing you need to do is instrument your activities so that the library can track start and stop events.
Instrumenting Your App¶
To determine time-in-app, the library needs to know when each activity is started and stopped. The library ships with instrumented Activity and ListActivity classes called InstrumentedActivity and InstrumentedListActivity. The simplest way to track start and stop events is to extend these classes for each of your activities.
If you would like to manually instrument your class, simply update your Activity’s onStart and onStop methods with the following:
@Override
public void onStart() {
super.onStart();
UAirship.shared().getAnalytics().activityStarted(this);
}
@Override
public void onStop() {
super.onStop();
UAirship.shared().getAnalytics().activityStopped(this);
}
Disabling Analytics¶
If you do not wish to include analytics and reporting in your application, simply add the following line to your airshipconfig.properties file:
analyticsEnabled = false
Support¶
For questions related to this release, bugs, or other concerns, don’t hesitate to email us at support@urbanairship.com, or visit our support site.
