urbanairship Module

Description

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

Getting Started

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

Note that there may be two versions of this module available to you, one for use with pre-1.8.0.1 SDKs and one for use with 1.8.0.1 or newer. In your tiapp.xml file, make sure that you specify the version of the module that corresponds to the version of Titanium Mobile SDK that you are targeting. For Appcelerator modules, specify the 1.X version of the module if building for versions of Titanium Mobile SDK prior to 1.8.0.1 and specify the 2.X version of the module if building for versions of Titanium Mobile SDK 1.8.0.1 or newer.

Using the 1.X version of the Urban Airship module

Additional steps may be required to use the 1.X version of the Urban Airship module. Please read the documentation included with the 1.X version of the module for additional instructions.

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 (https://go.urbanairship.com). 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: C2DM Configuration

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

Functions

Note: Versions of this module prior to 1.3 provided an 'options' property and a 'takeOff' function for specifying the options and initializing the push library. These have been deprecated in order to more closely match the functionality of the Urban Airship Android Push Library. Please see the 'Setup' section above for further details on initializing your application for push notifications.

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

c2dmId[string]

The C2DM registration ID currently associated with the device

Using this module

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-2011 by Appcelerator, Inc. All Rights Reserved. Please see the LICENSE file included in the distribution for further details.