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
- Cordova-CLI >= 7.0.0
- To use notifications:
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
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.
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.
// 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
)
<!-- 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.
UAirship.setUserNotificationsEnabled(true)