Getting Started

This guide is a high level overview of the Airship platform for Android and Amazon devices. We'll first cover the basic details of app setup before moving on to push notifications, client-side customization, and making use of our growing suite of integration and engagement tools.

Resources

There are a few important steps to get out of the way when integrating Airship with your app for the first time. Follow these instructions carefully to ensure that you will have a smooth development experience.

Push Provider Setup

FCM Setup

 Note

Google Cloud Messaging (GCM) has been rebranded to Firebase Cloud Messaging (FCM). Airship apps using GCM today should experience no issues, but Google strongly recommends that you upgrade your Android push notification transport system to Firebase as soon as possible.

Google Steps

Get Your Server Key

In order to configure your Airship application for FCM, you must first obtain an Server key from Google.

  1. Log in to the Firebase console.
     Note

    If you already have a Firebase project, open it now and skip to step 3.

  2. Click the Add project button, enter a project name in the window that opens, then click the Create Project button.
  3. In the left side menu, click and select Project settings.
  4. Select Cloud Messaging from the options at the top of the screen, then copy the Server key and Sender ID values for use in the Airship SDK step below.

Airship Steps

Configure the Android Service
  1. Open your project from the Airship dashboard and go to Settings » Channels » Mobile App Platforms.

  2. Click Configure for Android, enter the Server key from the completed Google Steps and the Firebase Package name.

  3. Click Save.

Next Steps

Configure the UA SDK

To send notifications, you must integrate the Airship SDK into your Android application. See: Android: SDK Installation.

ADM Setup

Amazon Device Messaging (ADM) is the transport method that Airship supports for Amazon notifications.

Amazon Steps

Get Your OAuth Credentials and API Key
 Note

While you will not need in-depth knowledge of Amazon's ADM platform in order to use ADM for push notifications, we recommend that you review Amazon's Overview of Amazon Device Messaging before continuing

  1. Log in to the Amazon Developer Console.

  2. Follow Amazon's documentation to obtain your OAuth Credentials and API Key.

  3. Navigate to Security Profiles » General, and save the Client ID and Client Secret (OAuth Credentials) values for use in the Airship SDK step below.
  4. Click the Android/Kindle Settings tab, copy the value of the API key, and paste it as the only data in a new text file named api_key.txt, which will be used in the API Key step below.
    For a release, or production, version of your app, see Store Your API Key as an Asset.

Airship Steps

Configure the Amazon Service
  1. Open your project from the Airship dashboard, and go to Settings » Channels » Mobile App Platforms.

  2. Click Configure for Amazon, then enter your Client ID and Client secret.

  3. Click Save.
Save the API Key

Save the api_key.txt file created above into your application’s assets directory: src/main/assets/.

Next Steps

Configure the UA SDK

To send notifications, you must integrate the Airship SDK into your Amazon application. See: Android/Amazon: SDK Installation.

SDK Installation

 Note

Applications are required to migrate to Jetpack (AndroidX) to use the SDK 11.0.0+ . For more information, see Migrating to AndroidX.

The Airship SDK is split into modules which allow you to choose the push providers included in your application. You can install more than one provider if you have a single APK that uses both ADM and FCM.

Artifact IdDescription
urbanairship-fcmFCM push provider support
urbanairship-admADM push provider support
urbanairship-ads-identifierAdvertising ID tracking
urbanairship-preferenceAndroid preferences
urbanairship-coreThe core module. Automatically included in the other modules

Current SDK version: 11.0.1

Example including FCM and ADM

dependencies {
  ...

  // Airship - FCM
  implementation "com.urbanairship.android:urbanairship-fcm:11.0.1"

  // Airship - ADM
  implementation "com.urbanairship.android:urbanairship-adm:11.0.1"
}
 Note

All Airship dependencies included in the build.gradle file should all specify the exact same version. The SDK will log an error if it detects urbanairship modules with mismatched version numbers at runtime.

Once you've chosen your modules, follow the setup steps below for each one.

SDK Setup for FCM

Add the urbanairship-fcm module as a dependency in your application. Then follow FCM Android Setup and FCM Push Provider Setup to configure your application to use FCM.

build.gradle

dependencies {
  ...

  // Airship - FCM
  implementation 'com.urbanairship.android:urbanairship-fcm:11.0.1'
}

If your application uses its own FirebaseMessagingService or some other third party push provider, you will also need to forward onNewToken and onMessageReceived received calls to the Airship SDK. For example:

FirebaseMessagingService
@Override
public void onNewToken() {
   AirshipFirebaseIntegration.processNewToken(getApplicationContext());
}

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
   AirshipFirebaseIntegration.processMessageSync(getApplicationContext(), message);
}

SDK Setup for ADM

Add the urbanairship-adm module as a dependency in your application. Then follow ADM Android Setup to configure Airship to use ADM.

build.gradle

dependencies {
  ...

  // Airship - ADM
  implementation 'com.urbanairship.android:urbanairship-adm:11.0.1'
}

Create Airship Config Options

Airship config options are a convenient way to pass custom settings to your app without needing to edit the source code. By default the Airship SDK loads these settings from the airshipconfig.properties file located in your application's assets directory. Use this file, among other things, to set the backend credentials for your app, and to toggle between development and production builds.

Example `airshipconfig.properties`
developmentAppKey = Your Development App Key
developmentAppSecret = Your Development App Secret

productionAppKey = Your Production App Key
productionAppSecret = Your Production Secret

# Toggles between the development and production app credentials
# Before submitting your application to an app store set to true
inProduction = false

# LogLevel is "VERBOSE", "DEBUG", "INFO", "WARN", "ERROR" or "ASSERT"
developmentLogLevel = DEBUG
productionLogLevel = ERROR

# Notification customization
notificationIcon = ic_notification
notificationLargeIcon = ic_large_notification
notificationAccentColor = #ff0000

# Optional, set the default notification channel
notificationChannel = customChannel

TakeOff

The Airship SDK must be initialized before any receiver, service, or activity is created. This is achieved by calling takeOff manually in the application's onCreate method or by using Autopilot .

Basic Autopilot integration
<meta-data android:name="com.urbanairship.autopilot"
          android:value="com.urbanairship.Autopilot"/>

Autopilot will automatically call takeOff when the application initializes without the need to override any Application methods. The class can be used directly to use configuration loaded from the airshipconfig.properties file.

Customizing Autopilot

Autopilot can also be extended to customize the airship config and to receive a callback when the Airship instance is ready.

Extending Autopilot example
public class SampleAutopilot extends AutoPilot {

  @Override
  public void onAirshipReady(@NonNull UAirship airship) {
      airship.getPushManager().setUserNotificationsEnabled(true);

      // Additional Airship SDK setup
  }

  @Override
  public AirshipConfigOptions createAirshipConfigOptions(@NonNull Context context) {
      AirshipConfigOptions options = new AirshipConfigOptions.Builder()
          .setDevelopmentAppKey("Your Development App Key")
          .setDevelopmentAppSecret("Your Development App Secret")
          .setProductionAppKey("Your Production App Key")
          .setProductionAppSecret("Your Production App Secret")
          .setInProduction(!BuildConfig.DEBUG)
          .setNotificationIcon(R.drawable.ic_notification)
          .setNotificationAccentColor(ContextCompat(getContext(), R.color.accent))
          .setNotificationChannel("customChannel")
          .build();

      return options;
  }
}

To extend Autopilot, add metadata within the application entry to the AndroidManifest.xml. The name of the meta-data com.urbanairship.autopilot and the value should be the fully qualified class name.

Register the extended Autopilot class
<meta-data android:name="com.urbanairship.autopilot"
          android:value="com.example.SampleAutopilot"/>

Send Your First Push Notification

At this point in the guide, if you followed all the steps above you should be ready to send a test push notification to verify everything is set up properly. Before sending a push, make sure you have enabled user notifications.

Enable user notifications
UAirship.shared().getPushManager().setUserNotificationsEnabled(true);

See Send Your First Message or our API reference for details on sending the first notification.

Deep Linking

Deep Linking provides a mechanism to open an application to a specific resource. The Airship Action framework supports the opening of deep links via the payload of a notification, a link from a Rich App Page or the JavaScript Interface. The Airship library only provides ways to trigger deep links; the application still needs to be set up to handle deep linking.

The default deep link action assumes that the application is set up to handle deep links through Android implicit intents. Implicit intents are intents used to launch components by specifying an action, category, and data instead of providing the component's class. This allows any application to invoke another application's component to perform an action. Only application components that are configured to receive the intent, by specifying an intent filter, will be considered.

Alternatively, you can customize how deep links are handled by setting a DeepLinkListener ont he UAirship instance during takeOff.

Example DeepLinkListener
    @Override
    public void onAirshipReady(@NonNull UAirship airship) {
        airship.setDeepLinkListener(deepLink -> {
            // Handle the deepLink
            return true;
        });
    }