Getting Started

This is a developers’ guide for setting up the Airship SDK for Cordova apps.

The Airship Cordova plugin allows a developer to integrate push notification services with Cordova apps targeting both Android and iOS. This plugin is designed to be cross-platform, and applications making use of it can leverage the same code on both platforms, with just a few API calls that are restricted to iOS or Android specifically. This document will walk you through the high level interaction between the Airship plugin and Cordova. We will also provide integration guides for both iOS and Android, so that you can get started quickly.

The Airship library provides a few different services for your application. The main functionality of the library is to facilitate integration with our Push Notification service, and we also provide support for location reporting and analytics.

Resources

Requirements

iOS

  • Requires Xcode 13+
  • Minimum iOS version supported 11+

Android

  • Minimum Android version supported 21+
  • Compile SDK version and Target SDK version 31+
  • Gradle Plugin version 3.0.0+
  • Java 8

Jetpack / AndroidX

This plugin requires modern Jetpack libraries (AndroidX). Enable AndroidX in your config.xml:

<preference name="AndroidXEnabled" value="true" />

Setup

The Airship module can be installed with the Cordova CLI:

cordova plugin add urbanairship-cordova

Optional: To use the AirshipLocationKit module (iOS Only), add the airship-location-cordova plugin:

cordova plugin add https://github.com/urbanairship/airship-location-cordova
 Note

Location functionality on the Android platform does not require a separate location module. For more information about the iOS location module see the Location docs.

Android only: Add a reference to your google-services.json file in the app’s config.xml

<platform name="android">
    ...
    <resource-file src="google-services.json" target="app/google-services.json" />
</platform>

iOS only: Add your Apple Developer Account Team ID to the build.json.

{
    "ios": {
        "debug": {
            "developmentTeam": "XXXXXXXXXX"
        },
        "release": {
            "developmentTeam": "XXXXXXXXXX"
        }
    }
}

Your iOS builds will need to reference the build.json using Cordova’s --buildConfig flag.

Initialize Airship

Before you can access any of the module’s API, the Airship module needs to be initialized. This can be accomplished by either calling takeOff when the device is ready, or automatically by providing config in the config.xml file.

 Note

An app can use both config.xml and takeOff call to initialize Airship, but app key/secret changes will not be applied until the next time the app starts.

Example calling takeOff when the device is ready
// TakeOff
UAirship.takeOff({
  production: {
    appKey: "<APP_KEY>",
    appSecret: "<APP_SECRET>"
  },
  development: {
    appKey: "<APP_KEY>",
    appSecret: "<APP_SECRET>"
  },
  site: "EU" // Optional. Add if app uses Airship's EU cloud site.
})

// Configure Android
UAirship.setAndroidNotificationConfig({
  icon: "ic_notification",
  largeIcon: "ic_notification_large",
  accentColor: "#FF0000"
})

// Configure iOS
UAirship.setPresentationOptions(
  UAirship.presentationOptions.sound | UAirship.presentationOptions.alert
)
Example config to allow automatic takeOff
<!-- Airship app credentials -->
<preference name="com.urbanairship.production_app_key" value="Your Production App Key" />
<preference name="com.urbanairship.production_app_secret" value="Your Production App Secret" />
<preference name="com.urbanairship.development_app_key" value="Your Development App Key" />
<preference name="com.urbanairship.development_app_secret" value="Your Development App Secret" />

<!-- Optional -->
<!-- Use EU cloud site -->
<preference name="com.urbanairship.site" value="EU" />

<!-- If the app is in production or not. If not set, Airship will auto detect the mode. -->
<preference name="com.urbanairship.in_production" value="true | false" />

<!-- Airship development log level defaults to debug -->
<preference name="com.urbanairship.development_log_level" value="none | error | warn | info | debug | verbose" />

<!-- Airship production log level defaults to error -->
<preference name="com.urbanairship.production_log_level" value="none | error | warn | info | debug | verbose" />

<!-- Enables/disables auto launching the message center when the corresponding push is opened. -->
<preference name="com.urbanairship.auto_launch_message_center" value="true | false" />

<!-- Android Notification Settings -->
<preference name="com.urbanairship.notification_icon" value="ic_notification" />
<preference name="com.urbanairship.notification_large_icon" value="ic_notification_large" />
<preference name="com.urbanairship.notification_accent_color" value="#0000ff" />

<!-- iOS Foreground Presentation Options -->
<preference name="com.urbanairship.ios_foreground_notification_presentation_alert" value="true | false"/>
<preference name="com.urbanairship.ios_foreground_notification_presentation_badge" value="true | false"/>
<preference name="com.urbanairship.ios_foreground_notification_presentation_sound" value="true | false"/>

<!-- iOS Auto Clear Badge -->
<preference name="com.urbanairship.clear_badge_onlaunch" value="true | false" />

Notification Service Extension

To take advantage of notification attachments, such as images, animated gifs, and video, you will need to create a notification service extension.

Follow the steps in the iOS Notification Service Extension Guide.

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, you must enable user notifications. The plugin does not enable user notifications by default in order to avoid prompting the user for permissions. But for testing purposes, you can enable user notifications as soon as the application is ready. You may also want to set default foreground presentation options to display the notification in the foreground.

Enable user notifications
UAirship.setUserNotificationsEnabled(true)