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

  3. In the left side menu, click the gear icon next, then select Project settings.
    Getting Started

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

Airship Steps

Configure the Android Service
  1. Open your project from the Airship dashboard, then navigate 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.
    Getting Started

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

    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, then navigate 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

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. However FCM and GCM modules should not be included in the same APK. In the off chance that both are included, the SDK will log an error message and default to using the FCM module.

Artifact IdDescription
urbanairship-fcmFCM push provider support.
urbanairship-gcmGCM push provider support.
urbanairship-admADM push provider support.
urbanairship-coreThe core module. Automatically included in the other modules
Example including FCM and ADM
dependencies {
  ...

  // Airship - FCM
  implementation 'com.urbanairship.android:urbanairship-fcm:9.7.1'
  implementation 'com.google.firebase:firebase-messaging:17.3.4'

  // Airship - ADM
  implementation 'com.urbanairship.android:urbanairship-adm:9.7.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:9.7.1'
  implementation 'com.google.firebase:firebase-messaging:17.3.4'
}

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

FirebaseInstanceIdService
@Override
public void onTokenRefresh() {
   // Notify Airship that the token is refreshed.
   AirshipFirebaseInstanceIdService.processTokenRefresh(getContext());
}
FirebaseMessagingService
@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
   AirshipFirebaseMessagingService.processMessageSync(getContext(), remoteMessage);
}

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:9.7.1'
}

SDK Setup for GCM

Add the urbanairship-gcm module as a dependency in your application. Then follow FCM Android Setup to configure Airship to use GCM/FCM.

build.gradle
dependencies {
  ...

  // Airship - GCM
  implementation 'com.urbanairship.android:urbanairship-gcm:9.7.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

# FCM/GCM Sender ID
fcmSenderId = Your Google API Project Number

# Notification customization
notificationIcon = ic_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);

      // Android O
      if (Build.VERSION.SDK_INT >= 26) {
          Context context = UAirship.getApplicationContext();
          NotificationManager notificationManager = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);

          NotificationChannel channel = new NotificationChannel("customChannel",
                  context.getString(R.string.custom_channel_name,
                  NotificationManager.IMPORTANCE_DEFAULT);

          notificationManager.createNotificationChannel(channel);
      }
  }

  @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)
          .setFcmSenderId("Your Google API Project Number") // FCM/GCM sender ID
          .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.

In this example, a single activity will be declared to handle all deep links for the app with the scheme vnd.urbanairship.sample and host deeplink. The activity will only exist long enough to open the deep link and will never be visible to the user. A complete example can be found in the Sample Application.

 Note

When selecting a scheme for deep linking, choose one unique enough so as not to conflict with other apps on the user's device, in order to avoid showing the user an app chooser.

Create the activity that parses the deep link:

public class ParseDeepLinkActivity extends Activity {
    public static final String PREFERENCE_DEEP_LINK = "/home/preferences";
    public static final String INBOX_DEEP_LINK = "/inbox/messages";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        Intent intent = getIntent();
        if (intent == null || intent.getData() == null) {
            finish();
        }

        openDeepLink(intent.getData());

        // Finish this activity
        finish();
    }

    private void openDeepLink(Uri deepLink) {
        String path = deepLink.getPath();

        if (PREFERENCE_DEEP_LINK.equals(path)) {
            // Launch preferences
            startActivity(new Intent(this, PushPreferencesActivity.class));
        } else if (INBOX_DEEP_LINK.equals(path)) {
            // Launch the inbox activity
            startActivity(new Intent(this, InboxActivity.class));
        } else {
            // Fall back to the main activity
            startActivity(new Intent(this, MainActivity.class));
        }
    }
}

Declare the activity in the AndroidManifest.xml file with the intent filter. The intent filter should accept the default intent action android.intent.action.VIEW and either android.intent.category.DEFAULT or android.intent.category.BROWSABLE category. It should also filter out any intents that do not contain a data URI with the scheme vnd.urbanairship.sample and host deeplink.

   <activity
       android:name=".ParseDeepLinkActivity"
       @android:style/Theme.NoDisplay>
       <intent-filter>
           <action android:name="android.intent.action.VIEW"/>

           <!-- Handles any vnd.urbanairship.sample://deeplink URI's -->
           <data android:scheme="vnd.urbanairship.sample" android:host="deeplink" />

           <category android:name="android.intent.category.DEFAULT"/>
           <category android:name="android.intent.category.BROWSABLE"/>
       </intent-filter>
</activity>

The application is now able to parse any predefined deep link paths. Alternatively, the ParseDeepLinkActivity could parse each segment of the path to construct a task stack using the Android TaskStackBuilder. This will enable sending any combination of deep links to define the entire task stack.

private void openDeepLink(Uri deepLink) {
    TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);

    // Treat each path segment of the URI as a deep link
    List<String> segments = deepLink.getPathSegments();

    // Create a task stack from the deep links
    if (segments != null) {
        for (String segment : segments) {
            Intent route = null;
            if ("preferences".equals(segment)) {
                route = new Intent(getApplicationContext(), PushPreferencesActivity.class);
            } else if ("inbox".equals(segment)) {
                route = new Intent(getApplicationContext(), InboxActivity.class);
            } else if ("home".equals(segment)) {
                route = new Intent(getApplicationContext(), MainActivity.class);
            }

            if (route != null) {
                stackBuilder.addNextIntentWithParentStack(route);
            }
        }
    }

    // Fall back to the main activity
    if (stackBuilder.getIntentCount() == 0) {
        stackBuilder.addNextIntent(new Intent(this, MainActivity.class));
    }

    // Launch the activities
    stackBuilder.startActivities();
}

The deep link's URI parameters can be used to pass extra data to one or more of the activities that are being invoked.

private Bundle parseOptions(Uri deepLink) {
    Bundle options = new Bundle();
    Map<String, List<String>> queryParameters = UriUtils.getQueryParameters(deepLink);

    if (queryParameters == null) {
        return options;
    }

    for (String key : queryParameters.keySet()) {
        List<String> values = queryParameters.get(key);
        if (values.size() == 1) {
            options.putString(key, values.get(0));
        } else if (values.size() > 1) {
            options.putStringArrayList(key, new ArrayList<String>(values));
        }
    }

    return options;
}

Before launching the activities in the task stack, set the extras on the last intent:

Bundle extras = parseOptions(deepLink);
if (extras != null) {
    // Add the extras to the last intent
    stackBuilder.editIntentAt(stackBuilder.getIntentCount() - 1).putExtras(extras);
}

// Launch the activities
stackBuilder.startActivities();

The app is now able to handle any deep links in the form of vnd.urbanairship.sample://deeplink/*. Where * is replaced with any deep link segments that the application knows how to parse and it will build the task stack in the specified order.

Example:

vnd.urbanairship.sample://deeplink/home/inbox?id=3 will launch the inbox activity on top of the main activity with the extra "id" with value "3".

If the implicit intent deep linking strategy does not work for the application, the deep link action can be overridden to provide any custom deep linking behavior.

Create a custom action that handles deep linking. The example assumes the deep link is still a URI, but any value that translates to a deep link can be used.

public class CustomDeepLinkAction extends Action {

    @Override
    public ActionResult perform(ActionArguments arguments) {
        Uri uri = UriUtils.parse(arguments.getValue().getString());

        String path = uri.getPath();
        Context context = UAirship.shared().getApplicationContext();

        Intent intent;
        if ("/home/preferences".equals(path)) {
            // Launch preferences
            intent = new Intent(context, PushPreferencesActivity.class);
        } else {
            // Fall back to the main activity
            intent = new Intent(context, MainActivity.class);
        }

        // Launch the activity
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        context.startActivity(intent);

        return ActionResult.newEmptyResult();
    }

    @Override
    public boolean acceptsArguments(ActionArguments arguments) {
        // Do any argument validation here.

        // Only accept String arguments
        if (arguments.getValue().getString() != null) {
            // Make sure we can parse the String as a Uri
            return UriUtils.parse(arguments.getValue().getString()) != null;
        }

        return false;
    }
}

Update the deep link action in the action registry after takeOff:

CustomDeepLinkAction action = new CustomDeepLinkAction();

ActionRegistry registry = UAirship.shared().getActionRegistry();
registry.getEntry(DeepLinkAction.DEFAULT_REGISTRY_NAME).setDefaultAction(action);