urbanairship Module

Description

This module allows the Urban Airship Android library to be used inside of Titanium. Push Notifications are supported.

Warning when Updating to Urban Airship v2.3.0

With the 2.3.0 update to the Urban Airship Module, several breaking changes have been made. When upgrading to 2.3.0, you will need to consider the following:

Message "An application restart is required" fires incorrectly

When clicking on a notification that activates your application, a "Restart Required" alert with the message "An application restart is required" may fire incorrectly. This is a known issue (TIMOB-9285) that can be resolved in your application by adding the following property to tiapp.xml:


        <property name="ti.android.bug2373.finishfalseroot" type="bool">true</property>

Make sure that the tiapp.xml file doesn't include any other ti.android.bug2373 properties.

Getting Started

View the Using Titanium Modules document for instructions on getting started with using this module in your application.

Accessing the urbanairship Module

To access this module from JavaScript, you would do the following:

var urbanairship = require("ti.urbanairship");

The urbanairship variable is a reference to the Module object.

Urban Airship Docs

Setup

Follow these steps to properly setup your Titanium Android application to use Urban Airship push notifications.

Step 1: Setting App Credentials

Urban Airship is initialized automatically when your Titanium application starts. However you still need to specify your app's credentials before it can interact with an application you've created on the Urban Airship dashboard. Urban Airship looks for these in a file called airshipconfig.properties, in the assets folder of your Android project directory.

Step 2: Enable push notifications

Enabling or disabling push notifications is a preference often best left up to the user, so by default, push is disabled in the module.

Step 3: Set additional options

Several additional options can be controlled in your application code.

Step 4: Register event listeners

Events are generated when application registration is complete and when a new message is received or clicked in the notification window.

Step 5: GCM Configuration

Please read the Getting Started with GCM documentation for additional information regarding using the GCM transport.

Functions

Events

urbanairship.EVENT_URBAN_AIRSHIP_SUCCESS

Called upon successful registration with Urban Airship.

urbanairship.EVENT_URBAN_AIRSHIP_ERROR

Called upon failure to register with Urban Airship.

urbanairship.EVENT_URBAN_AIRSHIP_CALLBACK

Called when a new push is received OR the user clicks the Android notification

Note:If you press the 'Back' hardware button or perform any other operation that causes the activity in which the module is loaded to be destroyed, your event listener will not be called if new notification messages are received. However, if you have set the urbanairship.showAppOnClick property to 'true' then the main activity will be re-launched when the user clicks on the Android notification. A notification for the message that was clicked will be processed when the activity registers for the urbanairship.EVENT_URBAN_AIRSHIP_CALLBACK event notification.

Properties

pushEnabled[boolean] (default: false)

Enables/disables push notifications. NOTE: When push notifications are enabled there may be a delay before the urbanairship.EVENT_URBAN_AIRSHIP_SUCCESS event is raised due to the latency in communicating with the server.

soundEnabled[boolean]

Enables/disables sound

vibrateEnabled[boolean]

Enables/disables vibration

isFlying[boolean]

Tests if Urban Airship has been initialized and is ready for use

showOnAppClick[boolean]

Indicates if your application should come forward when a user clicks (taps) an Urban Airship notification. (Default is 'false' if you don't set this property).

tags[string[]]

Tags can be used to categorize devices, and you can push notifications to devices with particular tags. WARNING: only call this after the module isFlying, or the call won't do anything.

alias[string]

Aliases are associated with device tokens, providing an alternate name. WARNING: only call this after the module isFlying, or the call won't do anything.

pushId[string]

The device's associated APID

Usage

Author

Jeff English

Module History

View the change log for this module.

Feedback and Support

Please direct all questions, feedback, and concerns to info@appcelerator.com.

License

Copyright(c) 2010-2013 by Appcelerator, Inc. All Rights Reserved. Please see the LICENSE file included in the distribution for further details.