Titanium

The Urban Airship Titanium Module allows a developer to integrate push notification services with Titanium 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.

To see sample code demonstrating the Urban Airship features discussed in this guide, check out the example included in the module on Bintray or Titanium Example on GitHub.

Setup

  1. Download the latest iOS and Android modules.

  2. Install the modules.

  3. Add the Urban Airship modules to the application’s tiapp.xml:

  4. Add your Urban Airship configuration to the application’s tiapp.xml:

    <ti:app>
        ...
    
        <!-- Production credentials -->
        <property name="com.urbanairship.production_app_key" type="string">Your Production App Key</property>
        <property name="com.urbanairship.production_app_secret" type="string">Your Production App Secret</property>
    
        <!-- Development credentials -->
        <property name="com.urbanairship.development_app_key" type="string">Your Development App Key</property>
        <property name="com.urbanairship.development_app_secret" type="string">Your Development App Secret</property>
    
        <!-- Selects between production vs development credentials -->
        <property name="com.urbanairship.in_production" type="bool">false</property>
    
        <!-- Android -->
        <property name="com.urbanairship.gcm_sender" type="String">GCM Sender ID or Project Number</property>
        <property name="com.urbanairship.notification_icon" type="string">Name of an icon in /project_name/platform/android/res/drawable folders, e.g. ic_notification.png</property>
        <property name="com.urbanairship.notification_accent_color" type="string">Notification accent color, e.g. #ff0000</property>
    
        <!-- iOS 10 alert foreground notification presentation option -->
        <property name="com.urbanairship.ios_foreground_notification_presentation_alert" type="bool">true | false</property>
        <!-- iOS 10 badge foreground notification presentation option -->
        <property name="com.urbanairship.ios_foreground_notification_presentation_badge" type="bool">true | false</property>
        <!-- iOS 10 sound foreground notification presentation option -->
        <property name="com.urbanairship.ios_foreground_notification_presentation_sound" type="bool">true | false</property>
    
    </ti:app>
    
  5. For iOS, enable remote-notification in the application’s tiapp.xml:

    <ti:app>
        ...
    
        <ios>
            <plist>
                <dict>
                    ...
                    <key>UIBackgroundModes</key>
                    <array>
                        <string>remote-notification</string>
                    </array>
                </dict>
            </plist>
        </ios>
    
     </ti:app>
    
  6. Import the module:

    var UrbanAirship = require('com.urbanairship');
    

Retrieving your Channel ID

The Channel ID will be logged for all apps. You can always get the Channel ID with this line in your application:

var channelId = UrbanAirship.channelId;

Enabling User Notifications

The Urban Airship SDK makes a distinction between “user notifications”, which can be seen by the user, and invisible notifications that carry only data for the app to process. Enabling or disabling user notifications is a preference often best left up to the user, so by default, user notifications are disabled.

UrbanAirship.userNotificationsEnabled = 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 EVENT_CHANNEL_UPDATED will be emitted when the channel is first created or updated due to registration changes. Example:

UrbanAirship.addEventListener(UrbanAirship.EVENT_CHANNEL_UPDATED, function(e) {
    Ti.API.info('Channel Updated' + UrbanAirship.channelId);
});

The EVENT_PUSH_RECEIVED will be emitted whenever a push is received when the application is foregrounded. The event will contain the message, extras, and the notification ID (Android only). Example:

UrbanAirship.addEventListener(UrbanAirship.EVENT_PUSH_RECEIVED, function(e) {
    Ti.API.info('Push received' + e.message);
});

Launch Notification

The notification that launched the application can be accessed with getLaunchNotification. The notification will contain the message, extras, and the notification ID. Example:

// Passing true to getLaunchNotification will clear the notification and
// cause subsequent calls to return null.
var launchNotification = UrbanAirship.getLaunchNotification(true);

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:

// Set tags
UrbanAirship.tags = ["some-tag", "other-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.

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:

UrbanAirship.namedUser = "coolNamedUserId";

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

UrbanAirship.namedUser = 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.