Getting Started
Integrate Airship with your app, and set up a push provider for Android and Amazon devices before sending your first push notification.
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.
Requirements
- Minimum Android version supported
21+
- Compile SDK version
31+
SDK Installation
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 and features to be included in your application.
Module | Description |
---|---|
urbanairship-core | The core module. Automatically included in the other modules. |
urbanairship-adm | ADM push provider |
urbanairship-fcm | FCM push provider |
urbanairship-hms | HMS push provider |
urbanairship-ads-identifier | Advertising ID tracking |
urbanairship-automation | In-App Automation, In-App Messaging, and Landing pages |
urbanairship-message-center | Message Center |
urbanairship-preference-center | Preference Center |
urbanairship-chat | Live Chat |
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"
}
All Airship dependencies included in the build.gradle file should all specify the exact same version.
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.
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
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
As of SDK 14.0, Open URL scoped URLs are now always verified.
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.
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.
Configure Airship Dashboard
Log in to the Firebase console.
Either create a new project or open an existing project that you want to configure with Airship.
Select Cloud Messaging from the options at the top of the screen, then copy the Server key.
Configure FCM in the Airship Dashboard using the Server key.
In Airship, go to Settings » Channels » Mobile Apps » Android.
Enter your Firebase server key and package name.
Click Add Android.
App Setup
Follow FCM Android Setup to configure your android application to connect to Firebase.
Add the
urbanairship-fcm
dependency to your application’s build.gradle file:implementation "com.urbanairship.android:urbanairship-fcm:$airshipVersion"
By default, the Airship SDK will use the data in google-services.json
to configure Firebase Messaging.
If your app makes use of multiple Firebase projects, you can configure the Airship SDK to initialize Firebase Messaging using a specific Firebase project using these instructions.
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.
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
Configure Airship Dashboard
- Follow Amazon’s documentation to obtain your OAuth Credentials and API Key.
- Configure Airship Amazon Channel with the OAuth Credentials.
- In Airship, go to Settings » Channels » Mobile Apps » Amazon.
- Enter your Client ID and Client secret.
- Click Save.
App Setup
Follow Amazon’s documentation to store your API key as an asset.
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
Follow Huawei’s documentation to configure app information in AppGallery Connect.
Log in to AppGallery Connect.
Go to My Apps and select the app you want to configure with Airship.
Enable Push service by following Huawei’s documentation.
Go to the Develop Overview and scroll to the bottom. Copy the
App ID
andApp secret
.Configure Airship Android Channel with the HMS Credentials.
In Airship, go to Settings » Channels » Mobile Apps » Android.
Enter your Huawei app ID and app secret.
Click Add Android.
App Setup
- Follow Huawei’s documentation) to set up the HMS SDK.
Airship requires HMS Core Push SDK 6.3.0.304 or newer.
- 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.
If necessary, please see our Troubleshooting Guide for help with common setup issues.
Categories