Getting Started

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.

Requirements

• Minimum Android version supported 21+
• Compile SDK version 31+

SDK Installation

The Airship SDK is split into modules which allow you to choose the push providers and features to be included in your application.

Current SDK version: 16.4.0

dependencies {

  def airshipVersion = "16.4.0"

  // ADM & FCM push providers
  implementation "com.urbanairship.android:urbanairship-fcm:$airshipVersion"
  implementation "com.urbanairship.android:urbanairship-adm:$airshipVersion"

  // In-App Messaging
  implementation "com.urbanairship.android:urbanairship-automation:$airshipVersion"

  // Message Center
  implementation "com.urbanairship.android:urbanairship-message-center:$airshipVersion"
}

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.getColor(context, R.color.color_accent))
          .setNotificationChannel("customChannel")
          // Uncomment this if your app uses Airship's EU cloud site
          //.setSite(AirshipConfigOptions.SITE_EU)
          .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 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")
                // Uncomment this if your app uses Airship's EU cloud site
                //.setSite(AirshipConfigOptions.SITE_EU)
                .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"/>

URL Allow List

The UrlAllowList controls which URLs the Airship SDK is able to act on. The SDK divides up usages of URLs into two different scopes:

• SCOPE_OPEN_URL: Only URLs allowed for this scope can be opened from an action, displayed in landing page, displayed in an HTML in-app message, or displayed as media in an In-App Automation. Defaults to any Airship-originated URLs and YouTube URLs.
• SCOPE_JAVASCRIPT_INTERFACE: These URLs are checked before the Airship JavaScript interface is injected into the webview. Defaults to any Airship originated URLs.

The easiest way to expand the list of allowed URLs is to provide a list of URL patterns in the AirshipConfig.

# SCOPE_OPEN_URL
urlAllowListScopeOpenUrl = *, https://*.mycompany.com

# SCOPE_JAVASCRIPT_INTERFACE
urlAllowListScopeJavaScriptInterface = https://*.mycompany.com

# Applies to both SCOPE_OPEN_URL & SCOPE_JAVASCRIPT_INTERFACE
urlAllowList = https://*.mycompany.com

<pattern> := '*' | <scheme>'://'<host>/<path> | <scheme>'://'<host> | <scheme>':/'<path> | <scheme>':///'<path>
<scheme> := <any char combination, '*' are treated as wild cards>
<host> := '*' | '*.'<any char combination except '/' and '*'> | <any char combination except '/' and '*'>
<path> := <any char combination, '*' are treated as wild cards>

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 on the 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 })
}

Push Provider Setup

Before your application is able to receive push notifications, you must configure at least one push provider.

FCM

Firebase Cloud Messaging (FCM) is the transport method that Airship supports for Android devices that have access to the Google Play store.

Configure Airship Dashboard

1. Log in to the Firebase console.

2. Either create a new project or open an existing project that you want to configure with Airship.

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.

   

5. Configure FCM in the Airship Dashboard using the Server key.

   1. In Airship, go to Settings » Channels » Mobile Apps » Android.

   2. Enter your Firebase server key and package name.

   3. Click Add Android.

App Setup

1. Follow FCM Android Setup to configure your android application to connect to Firebase.

2. Add the urbanairship-fcm dependency to your application’s build.gradle file:

   implementation "com.urbanairship.android:urbanairship-fcm:$airshipVersion"

Extending the FirebaseMessagingService

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(String token) {
   AirshipFirebaseIntegration.processNewToken(getApplicationContext());
}

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

fun onNewToken(token: String) {
   AirshipFirebaseIntegration.processNewToken(getApplicationContext())
}

fun onMessageReceived(remoteMessage: RemoteMessage) {
   AirshipFirebaseIntegration.processMessageSync(getApplicationContext(), message)
}

ADM

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

Configure Airship Dashboard

1. Follow Amazon’s documentation to obtain your OAuth Credentials and API Key.
2. Configure Airship Amazon Channel with the OAuth Credentials.
   1. In Airship, go to Settings » Channels » Mobile Apps » Amazon.
   2. Enter your Client ID and Client secret.
   3. Click Save.

App Setup

1. Follow Amazon’s documentation to store your API key as an asset.

2. Add the urbanairship-adm dependency to your application’s build.gradle file:

   implementation "com.urbanairship.android:urbanairship-adm:$airshipVersion"

HMS

Huawei Mobile Services (HMS) is the transport method that Airship supports for Huawei devices that do not have access to the Google Play Store.

Configure Airship Dashboard

1. Follow Huawei’s documentation to configure app information in AppGallery Connect.

2. Log in to AppGallery Connect.

3. Go to My Apps and select the app you want to configure with Airship.

4. Enable Push service by following Huawei’s documentation.

   

5. Go to the Develop Overview and scroll to the bottom. Copy the App ID and App secret.

   

6. Configure Airship Android Channel with the HMS Credentials.

   1. In Airship, go to Settings » Channels » Mobile Apps » Android.

   2. Enter your Huawei app ID and app secret.

   3. Click Add Android.

App Setup

1. Follow Huawei’s documentation) to set up the HMS SDK.

1. Add the urbanairship-hms dependency to your application’s build.gradle file:

   implementation "com.urbanairship.android:urbanairship-hms:$airshipVersion"

Extending the HmsMessageService

If your application uses its own HmsMessageService 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(@Nullable String token) {
   AirshipHmsIntegration.processNewToken(getApplicationContext(), token);
}

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

fun onNewToken(token: String?) {
   AirshipHmsIntegration.processNewToken(getApplicationContext(), token)
}

fun onMessageReceived(remoteMessage: RemoteMessage) {
   AirshipHmsIntegration.processMessageSync(getApplicationContext(), message)
}

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().pushManager.userNotificationsEnabled = true

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