map-o file-code-o arrow-directionplatform-webreach-project-type-boarding-passreach-project-type-couponreach-project-type-event-ticketreach-project-type-genericreach-project-type-gift-cardreach-project-type-loyalty-cardreach-project-type-member-card pictures more_vert chain

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

Getting Started

Requirements

Setup

Install the plugin:

$ cordova plugin add urbanairship-cordova

Example config.xml

<!-- 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" />

<!-- Required for Android. -->
<preference name="com.urbanairship.gcm_sender" value="Your GCM Sender ID" />

<!-- If the app is in production or not -->
<preference name="com.urbanairship.in_production" value="true | false" />

<!-- Optional config values -->

<!-- Enable push when the application launches -->
<preference name="com.urbanairship.enable_push_onlaunch" value="true | false" />

<!-- Enable Analytics when the application launches -->
<!-- Warning: Features that depend on analytics being enabled may not work properly if analytics is disabled (reports, location segmentation, region triggers, push to local time). -->
<preference name="com.urbanairship.enable_analytics" 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" />

<!-- Override the Android notification icon -->
<preference name="com.urbanairship.notification_icon" value="ic_notification" />

<!-- Override the Android notification sound (sound file should be in res/raw)-->
<preference name="com.urbanairship.notification_sound" value="push" />

<!-- Specify the notification accent color for Android API 21+ (Lollipop) -->
<preference name="com.urbanairship.notification_accent_color" value="#0000ff" />

<!-- Clear the iOS badge on launch -->
<preference name="com.urbanairship.clear_badge_onlaunch" value="true | false" />

<!-- iOS 10 alert foreground notification presentation option -->
<preference name="com.urbanairship.ios_foreground_notification_presentation_alert" value="true | false"/>

<!-- iOS 10 badge foreground notification presentation option -->
<preference name="com.urbanairship.ios_foreground_notification_presentation_badge" value="true | false"/>

<!-- iOS 10 sound foreground notification presentation option -->
<preference name="com.urbanairship.ios_foreground_notification_presentation_sound" value="true | false"/>

This plugin uses cocoapods to install the iOS Urban Airship SDK, which is supported in cordova-ios 4.3.0. Ensure cocoapods is installed and the pod repo is updated via pod repo update. If using Xcode directly, open the xcworkspace instead of the xcodeproj.

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

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 devices. 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 the application until it is either reinstalled, or its internal data is cleared.

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")

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 20 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 Tag Group Walkthrough will guide you through the creation of your first Tag Group.

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 Messaging and In-App Messaging Quick Start Guide.

Display

By default, in-app messages will only display a single banner on app foreground after a three-second delay.

Display ASAP Mode

Enabling display ASAP:

UAirship.setDisplayASAPEnabled(true)

Exercise caution when using display ASAP mode. The default auto display behavior for in-app messages is designed to offer a balance between immediacy and user experience, by minimizing the chance of accidentally disrupting the user’s activities in your app. Push automation may also occasionally see latencies that result in associated in-app messages being displayed in unexpected contexts.

Enabling display ASAP mode will cause the SDK to display the in-app message on arrival. If the app is currently in the background, the in-app message will be displayed on the next foreground after the auto display delay. If a message is already displaying when a new in-app message is received, the new message will be displayed once the currently displayed message is dismissed, after the autodisplay delay.