Cordova

The Urban 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 Urban Airship plugin and Cordova. We will also provide integration guides for both iOS and Android, so that you can get started quickly.

The Urban 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

Setup

The Urban Airship module can be installed with the cordova cli:

cordova plugin add urbanairship-cordova

(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 Urban Airship

Calling takeOff when the device is ready:

// TakeOff
UAirship.takeOff({
  production: {
    appKey: "<APP_KEY>",
    appSecret: "<APP_SECRET>"
  },
  development: {
    appKey: "<APP_KEY>",
    appSecret: "<APP_SECRET>"
  }
})

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

// Configure iOS
UAirship.setPresentationOptions(
  UAirship.presentationOptions.sound | UAirship.presentationOptions.alert
)

Before you can access any of the module's API, Urban 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 Urban Airship, but app key/secret changes will not be applied until the next time the app starts.

Example config to allow automatic takeOff:

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

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

<!-- Urban 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

In order to take advantage of iOS 10 notification attachments, such as images, animated gifs, and video, you will need to create a notification service extension by following the iOS Notification Service Extension Guide.

Send Your First Push Notification

UAirship.setUserNotificationsEnabled(true)

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 a 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 on iOS 10. On older iOS devices, make sure you background the app before sending the push.

Urban Airship Channel IDs

Getting the Channel ID:

UAirship.getChannelID(function (channelID) {
     console.log("Channel: " + channelID)
 })

The Channel ID is a unique identifier that ties together an application/device pair on a mobile device. The Channel ID is used to target pushes to specific devices using the Urban Airship API. Once a Channel ID is created, it will persist in the application. It may or may not change when the application is reinstalled. For more information on platform-specific operation, see the Android and iOS documentation.

Don't worry if this value initially comes back as null on your app's first run (or after clearing the application data), as the Channel ID will be created and persisted during registration. To receive an event when the Channel ID is created, see Listening for Events.

Enabling User Notifications

UAirship.setUserNotificationsEnabled(true)

The Urban Airship SDK makes a distinction between "user notifications", which can be seen by the user, and other forms of push that allow you to send data to your app silently, or in the background. Enabling or disabling user notifications is a preference often best left up to the user, so by default, user notifications are disabled.

Listening for Events

Example:

// Register for any Urban Airship events
document.addEventListener("urbanairship.registration", function (event) {
    if (event.error) {
        console.log('There was an error registering for push notifications')
    } else {
        console.log("Registered with ID: " + event.channelID)
    }
})

// Register for any Urban Airship push events
document.addEventListener("urbanairship.push", function (event) {
    console.log("Incoming push: " + event.message)
})

The JavaScript API follows an asynchronous callback approach with hooks for events such as Push registration and incoming messages.

Addressing Devices

To help target specific devices or users for a notification, we have Tags, Named Users and Tag Groups.

Tags

Example:

UAirship.setTags(["loves_cats", "shops_for_games"], function () {

    UAirship.getTags(function (tags) {
        tags.forEach(function (tag) {
            console.log("Tag: " + tag)
        })
    })

})

Tags allow you to attribute arbitrary metadata to a specific device. Common examples include favorites such as sports teams or news story categories.

Named Users

UAirship.setNamedUser("NamedUserID")
Note

Associating the channel with a Named User ID will implicitly disassociate the channel from the previously associated Named User ID, if it existed.

Named Users allow you to associate multiple devices to a single user or profile that may be associated with more than one device, e.g., an end-user's Android phone and tablet. A device can have only one Named User, and a single Named User should not be associated with more than 50 devices. Named Users provide the ability to directly set tags on them (see Tag Groups).

By default, Named Users cannot be associated from the device. In this case if the devices attempts a Named User association, the association will fail and the plugin will log an error. In order to change this setting, see the Settings documentation.

Tag Groups

Channel Tag Group Example:

UAirship.editChannelTagGroups()
        .addTags("loyalty", ["silver-member"])
        .removeTags("loyalty", ["bronze-member"])
        .apply()

Named User Tag Group Example:

UAirship.editNamedUserTagGroups()
        .addTags("loyalty", ["silver-member"])
        .removeTags("loyalty", ["bronze-member"])
        .apply()

Tag groups are configurable namespaces for organizing tags for the channel and Named User. Please view the Tag Groups documentation for more details. The Create and push to a tag group guides you through creating and using Tag Groups.

By default, Tag Groups cannot be modified from the device. In this case if a device attempts to modify Tag Groups, the modification will fail and the SDK will log an error. In order to change this setting, see the Settings documentation.

Custom Events

var event = {
    "name": "Event name",
    "value": 123.45
}

UAirship.addCustomEvent(event)

Custom events let you track user activities and key conversions in your application, and tie them back to corresponding push messaging campaigns. Custom events requires analytics to be enabled. If disabled, any event that is added to analytics will be ignored. For a more detailed explanation on custom events and possible use cases, see the Custom Events topic guide.

Message Center

The default message center can be displayed at any time.

UAirship.displayMessageCenter()

The message center can be dismissed:

UAirship.dismissMessageCenter()

To display the inbox message:

UAirship.displayInboxMessage("theInboxMessageID")

The inbox message can be dismissed:

UAirship.dismissInboxMessage()

To display the overlay inbox message:

UAirship.overlayInboxMessage("theInboxMessageID")

The overlay inbox message can be dismissed:

UAirship.dismissOverlayInboxMessage()

To delete an inbox message:

UAirship.deleteInboxMessage("theInboxMessageID")

To mark an inbox message read:

UAirship.markInboxMessageRead("theInboxMessageID")

Urban Airship Message Center is a place in your app where you can display persistent rich messages, including HTML, video, etc. The messages are hosted by Urban Airship, and are typically displayed in standard inbox-style within your app.

In-App Messaging

In-App Messages are banner notifications that appear inside of your app, regardless of the opt-in/opt-out status of a user. For more details, see: In-App Messages.