Resources

• Sample App
• API Docs
• Troubleshooting guide
• Github Repo (SDK & Sample App)
• SDK migration guides

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

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. In Airship, go to Settings » Channels » Mobile App.

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

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. In Airship, go to Settings » Channels » Mobile App.

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

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.

Current SDK version: 12.2.0

dependencies {
  ...

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

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

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.

dependencies {
  ...

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

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:

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

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

fun onNewToken() {
  AirshipFirebaseIntegration.processNewToken(getApplicationContext())
}

fun 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.

dependencies {
  ...

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

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.

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

EU Cloud Site

If your app uses Airship’s EU cloud site, you will need to add that to airshipconfig.properties.

# EU Cloud Site
site = EU

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 .

<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.

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;
  }
}

class SampleAutopilot : AutoPilot() {
    override fun onAirshipReady(airship: UAirship) {
        airship.getPushManager().setUserNotificationsEnabled(true)
        // Additional Airship SDK setup
    }

    override fun createAirshipConfigOptions(context: Context): AirshipConfigOptions {
        return com.urbanairship.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.getColor(context, R.color.background_dark))
                .setNotificationChannel("customChannel")
                .build()
    }
}

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.

<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.

UAirship.shared().getPushManager().setUserNotificationsEnabled(true);

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.

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

fun onAirshipReady(airship: UAirship) {
   airship.setDeepLinkListener(DeepLinkListener { deepLink: String? -> true })
}