Install & Setup the Android SDK

Requirements

• Minimum Android version supported: 23+
• Compile SDK version: 36+

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.

Choose the UI framework that matches your app: use -compose modules if using Jetpack Compose, otherwise use the standard modules. Do not include both modules in the same app.

dependencies {

    val airshipVersion = "androidSdkVersion"
    
    // FCM push provider
    implementation("com.urbanairship.android:urbanairship-fcm:$airshipVersion")
    
    // In-App Messaging
    implementation("com.urbanairship.android:urbanairship-automation-compose:$airshipVersion")
    
    // Message Center
    implementation("com.urbanairship.android:urbanairship-message-center-compose:$airshipVersion")
}

dependencies {

    def airshipVersion = "androidSdkVersion"
    
    // FCM push provider
    implementation "com.urbanairship.android:urbanairship-fcm:$airshipVersion"
    
    // In-App Messaging
    implementation "com.urbanairship.android:urbanairship-automation:$airshipVersion"
    
    // Message Center
    implementation "com.urbanairship.android:urbanairship-message-center:$airshipVersion"
}

Initialize Airship

The Airship SDK must be initialized before any Receiver, Service, or Activity is created. The recommended way to achieve this is by using the Autopilot class, but it is also possible to call takeOff manually in Application.onCreate.

Setup Autopilot

The Airship SDK will automatically launch and load an Autopilot class that can be used to provide custom Airship config and to customize the Airship instance. Autopilot is the recommended approach to integrating the Airship SDK.

To start, create a new class that extends Autopilot. This class needs to be public and have a default no argument constructor.

class SampleAutopilot : Autopilot() {

}

public class SampleAutopilot extends 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.

<application
    android:name="com.example.SampleApp">

    <meta-data android:name="com.urbanairship.autopilot"
        android:value="com.example.SampleAutopilot" />

    <!-- ... -->
</application>

Configuring Airship

Airship requires app credentials (app key and app secret) to authenticate your application. You can find these in the Airship dashboard under Settings → APIs & Integrations → App Keys.

The AirshipConfigOptions provides the app credentials and common settings for Airship. To provide an AirshipConfigOptions instance, override the method createAirshipConfigOptions in your autopilot class.

class SampleAutopilot : Autopilot() {

    override fun createAirshipConfigOptions(context: Context) =
        airshipConfigOptions {
            // Set default credentials. Alternatively, you can set production and development separately.
            setAppKey("YOUR_DEFAULT_APP_KEY")
            setAppSecret("YOUR_DEFAULT_APP_SECRET")

            // Set site. (Either Site.SITE_US or Site.SITE_EU)
            setSite(Site.SITE_US)

            // Notification config
            setNotificationAccentColor(context.getColor(R.color.accent))
            setNotificationIcon(R.drawable.ic_notification)
            setNotificationChannel(NotificationProvider.DEFAULT_NOTIFICATION_CHANNEL)
        }

    override fun onAirshipReady(context: Context) {
        // Airship is ready! Configure additional settings here.
        Airship.push.userNotificationsEnabled = true
    }
}

public class SampleAutopilot extends Autopilot {

    @Override
    public @Nullable AirshipConfigOptions createAirshipConfigOptions(@NotNull Context context) {
        return AirshipConfigOptions.newBuilder()
                // Set default credentials. Alternatively, you can set production and development separately.
                .setAppKey("YOUR_DEFAULT_APP_KEY")
                .setAppSecret("YOUR_DEFAULT_APP_SECRET")

                // Set site. (Either SITE_US or SITE_EU)
                .setSite(Site.SITE_US)

                // Notification config
                .setNotificationAccentColor(context.getColor(R.color.accent))
                .setNotificationIcon(R.drawable.ic_notification)
                .setNotificationChannel(NotificationProvider.DEFAULT_NOTIFICATION_CHANNEL)
                                   
                .build();
    }

    @Override
    public void onAirshipReady(@NotNull Context context) {
        // Airship is ready! Configure additional settings here.
        Airship.getPush().setUserNotificationsEnabled(true);
    }
}

Customizing Airship behavior

Airship provides common config options in AirshipConfig, however some more advanced configuration must be set directly on the Airship instance. Custom push handling, deep linking, etc., should be configured during onAirshipReady callback. This will ensure Airship is properly configured before handling any messages.

The onAirshipReady callback will be called on a background thread during Airship init process. Applications should not do any long-running work during this callback, or it might prevent Airship from being ready in time to process a push notification.

class SampleAutopilot : Autopilot() {
    // ...

    override fun onAirshipReady(context: Context) {
        // Custom Message Center
        MessageCenter.shared().setOnShowMessageCenterListener { messageId: String? ->
            true
        }

        // Notification handling
        Airship.push.addPushListener(MyPushListener())
        Airship.push.notificationListener = MyNotificationListener()

        // etc...
    }
}

public class SampleAutopilot extends Autopilot {

    // ...

    @Override
    public void onAirshipReady(@NonNull Context context) {
        MessageCenter.shared().setOnShowMessageCenterListener(messageId -> {
            return true;
        });
        Airship.getPush().addPushListener(new MyPushListener());
        Airship.getPush().setNotificationListener(new MyNotificationListener());
    }
}

Test the integration

After completing the setup, verify your integration:

1. Build and run your app on your Android device or emulator.
2. Check the logcat output for Airship channel creation:
   • Look for a log message similar to: Airship channel created: <CHANNEL_ID>
   • The channel ID will appear in the log output, confirming successful initialization.
   • For more detailed logging, see Logging.

If you see the channel ID in the logcat and no errors, your integration is successful. You can now proceed with configuring deep links, push notifications, and other Airship features.

If you don’t see a channel ID in the logcat or encounter errors during initialization, see the Troubleshooting guide for common problems and solutions.