PhoneGap

The Urban Airship PhoneGap/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.

To see sample code demonstrating the Urban Airship features discussed in this guide, check out the PhoneGap Example on GitHub.

Push Notifications

Push Notifications sent through the Urban Airship API can carry an alert string, as well as arbitrary key/value pairs in the payload. On the iOS platform we support badging, and both platforms support our proprietary solution known as Quiet Time, which allows your users to specify timespans when they would prefer the app to keep quiet (such as at night).

Location

Location reporting is a powerful way to keep track of your users and address location-specific market segments. The provided API allows you to record a device’s GPS location in either one-shot or continuous reporting modes, with full control over frequency and distance thresholds, for optimal battery usage.

Reports

Besides providing location data, the Urban Airship library also captures realtime events that let you see how users are interacting with the pushes you send. Metrics such as push conversions (when users enter your app after receiving a push), time-in-app, and other such data are sent to our servers for view in the Urban Airship web portal.

Getting Started

Production vs. Development Apps in Urban Airship

Urban Airship makes a hard distinction between development and production versions of your app, each with their own distinct credentials and settings in the backend. This is so you can test in development without necessarily running the risk of sending test messages to users. Before doing any mobile integration, begin by creating development and production versions of your app in the Urban Airship dashboard.

Requirements

  • Cordova-CLI >= 6.4.0
  • CocoaPods version >= 1.1.1

Setup

  • Set up push for iOS and Android

  • Install CocoaPods

    This plugin uses cocoapods 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.

  • Install the urbanairship-cordova plugin

$ cordova plugin add urbanairship-cordova
  • Modify config.xml file to include the UAirship config
<!-- 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" />

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

Retrieving your Channel ID

The Channel ID is a unique identifier that ties together an application/device pair on Android and iOS 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.

The Channel ID will be logged for all apps. You can always get the Channel ID with a couple of extra lines to your application:

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

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.

Enabling User Notifications

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.

UAirship.setUserNotificationsEnabled(true)

Send a Test Notification

Now would be a great time to send a test notification. See our user guide on Send Your First Notification to get started using our dashboard interface, or our API reference for more details.

Listening for Events

The JavaScript API follows an asynchronous callback approach with hooks for events such as Push registration and incoming messages. Below is a brief example of this API in use:

// 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)
})

Addressing Devices

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

Tags

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

Example:

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

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

})

Named Users

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.

Examples:

Once the application has a channel ID, you can associate the channel to a Named User:

UAirship.setNamedUser("NamedUserID")

To disassociate a channel from a Named User ID, set its ID to null:

UAirship.setNamedUser(null)

Note

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

Tag Groups

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.

Channel Tag Groups

Once you have created a Tag Group, you can add or remove tags for the Tag Group on the channel. In this example, we have created a Tag Group loyalty and will upgrade a user from “bronze-member” to “silver-member”:

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

Named User Tag Groups

Named users provide the ability to directly set tags on them. Once you have created a Tag Group and associated a channel with the Named User, you can add or remove tags for the Tag Group on that Named User in a similiar fashion as Channel Tag Groups.

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

Custom Events

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.

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

UAirship.addCustomEvent(event)

Message Center

The default message center can be displayed at any time.

UAirship.displayMessageCenter()

Plugin Reference

JSDocs are available that detail every method and event provided by the plugin.