Skip to content
Titanium SDK

Version13.3.1

You are reading 13.3.1. See this page in 13.4.1.

Titanium.Android

moduleAndroidsince 1.5

Extends Titanium.ModuleTitanium.Proxy

The top-level Android module.

The Android module allows the application to manage various Android components.

Action Bar

An action bar is a UI feature that identifies the application and user location, and provides user actions and navigation modes.

The Titanium SDK lets you customize the look of the action bar and add action items. Action items are added using the Titanium.Android.Menu API.

For more information about the action bar, see the Titanium.Android.ActionBar API reference.

Activities

An Android application is made up of one or more activities. Each activity represents a single screen with a user interface.

In Titanium, each Window or TabGroup has its own activity. The application can access the activity of a Window and TabGroup object and monitor its lifecycle events. Titanium also lets you launch new activities by creating intents to launch them. See the "Intents" section below.

For more information about activities, see the Titanium.Android.Activity API reference.

Broadcast Intents and Receivers

Broadcast Intents allow your application to send out a message to any application that sets up a Broadcast Receiver to listen to it. Your application can also register Broadcast Receivers to listen to system events sent by the Android OS, such as low battery warnings or airplane mode changes.

For more information about broadcasts, see the Android Broadcast Intents and Receivers guide and Titanium.Android.BroadcastReceiver API reference.

Intents

Intents are message objects that specify actions to perform which can start either activities, broadcasts or services.

For more information about intents, see the Titanium.Android.Intent API reference.

Intent Filters

Intent Filters advertise to the Android OS that your application handles certain actions and data types. For example, when another application wants to share an image or text, your application can define intent filters to let Android know your application can handle those data types.

For more information about intent filters, see the Android Intent Filters guide.

Notifications

Notifications alert the user that something is happening to your application while it is in the background. Notifications appear in the notification drawer until the user clears them and on the lock screen for devices running Android 5.0 or greater. Note that the user can filter or turn notifications on and off from Settings. For more information about notifications, see the Titanium.Android.Notification API reference.

For Android toast notifications (pop-up notifications sent while the application is in the foreground), see Titanium.UI.Notification.

Options Menu

The options menu is a feature of older Android devices (prior to Android 3.0 (API 11)), and has been replaced by the action bar. The options menu is accessed by pressing the Menu and presents a pop-up menu of options the user can execute.

The Titanium.Android.Menu API is used to construct both the options menu and action items for the action bar.

For more information about the options menu, see the Titanium.Android.Menu API reference.

Services

A service is a component started by an application that runs in the background. The service does not have any application UI associated with it, so the user does not directly interact with it, only your application.

The Titanium SDK gives you the ability to write your own Android Services using JavaScript. The service executes your JavaScript code at intervals you specify. Note that the service will stop running when you back out of the app. So, if you want the service to continue running, then it's recommended that you set the root window's exitOnClose property to false so that the window will persist in the background like iOS.

For more information about services, see the Titanium.Android.Service API reference.

Permissions

Starting from Android 6.0 (API level 23), users need to grant certain permissions to apps while the app is running. You can read it more here. Starting with Android 13 you have to use more granular media permissions. Check the official documentation. Make sure to add e.g. <uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/> to your tiapp.xml too.

In Titanium SDK, to support this, we have the Titanium.Android.requestPermissions method. It is used to request any permission you may need. An example of using it is shown below:

var permissions = [ 'android.permission.CAMERA', 'android.permission.READ_EXTERNAL_STORAGE', 'android.permission.WRITE_EXTERNAL_STORAGE' ];
if (Ti.Platform.versionMajor >= 13) {
  // example for camera and image permission on Android 13
  permissions = [ 'android.permission.CAMERA', 'android.permission.READ_MEDIA_IMAGES' ]
}
Ti.Android.requestPermissions(permissions, function (e) {
    if (e.success) {
        Ti.API.info('SUCCESS');
    } else {
        Ti.API.info('ERROR: ' + e.error);
    }
});

Properties 240

ACTION_BOOT_COMPLETED

Stringread-only

Indicates the system has finished booting.

Pass to the Titanium.Android.registerBroadcastReceiver method to listen to the system broadcast.

The application needs to also set the android.permission.RECEIVE_BOOT_COMPLETED permission in the Android manifest section of the tiapp.xml file.

<ti:app>
    <android>
        <manifest>
            <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
        </manifest>
    </android>
</ti:app>

See Intent.ACTION_BOOT_COMPLETED in the Android API Reference.

ACTION_NEW_OUTGOING_CALL

Stringread-only

An outgoing call is about to be placed.

Pass to the Titanium.Android.registerBroadcastReceiver method to listen to the system broadcast.

The application needs to also set the android.permission.NEW_OUTGOING_CALL permission in the Android manifest section of the tiapp.xml file.

<ti:app>
    <android>
        <manifest>
            <uses-permission android:name="android.permission.NEW_OUTGOING_CALL"/>
        </manifest>
    </android>
</ti:app>

See Intent.ACTION_NEW_OUTGOING_CALL in the Android API Reference.

apiName

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

Indicates if the proxy will bubble an event to its parent.

Default: true

EXTRA_UID

Stringread-only

UID of the assigned packaged.

Sent with the Titanium.Android.ACTION_UID_REMOVED broadcast, and may be sent with the Titanium.Android.ACTION_PACKAGE_CHANGED and Titanium.Android.ACTION_PACKAGE_REMOVED broadcasts.

See Intent.EXTRA_UID in the Android API Reference.

FOREGROUND_SERVICE_TYPE_CAMERA

Numbersince 9.3.0read-only

Allows the camera to be used while the app is in the background.

This constant is passed to the Titanium.Android.Service.foregroundNotify method.

To use this constant, you must also set your <service/> element to the foregroundServiceType attribute value as shown below.

<ti:app>
    <android>
        <services>
            <service url="<YourService.js>" android:foregroundServiceType="camera"/>
        </services>
    </android>
</ti:app>

See Google's ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA documentation for more details.

FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE

Numbersince 8.3.0read-only

Allows connecting to Android Auto, bluetooth, TV or other devices while app is in the background.

This constant is passed to the Titanium.Android.Service.foregroundNotify method.

To use this constant, you must also set your <service/> element to the foregroundServiceType attribute value as shown below.

<ti:app>
    <android>
        <services>
            <service url="<YourService.js>" android:foregroundServiceType="connectedDevice"/>
        </services>
    </android>
</ti:app>

See Google's ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE documentation for more details.

FOREGROUND_SERVICE_TYPE_LOCATION

Numbersince 8.3.0read-only

Allows accessing location from the GPS, map, etc. while the app is in the background.

This constant is passed to the Titanium.Android.Service.foregroundNotify method.

To use this constant, you must also set your <service/> element to the foregroundServiceType attribute value as shown below.

<ti:app>
    <android>
        <services>
            <service url="<YourService.js>" android:foregroundServiceType="location"/>
        </services>
    </android>
</ti:app>

See Google's ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION documentation for more details.

FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK

Numbersince 8.3.0read-only

Allows music, video, news or other media playback while the app is in the background.

This constant is passed to the Titanium.Android.Service.foregroundNotify method.

To use this constant, you must also set your <service/> element to the foregroundServiceType attribute value as shown below.

<ti:app>
    <android>
        <services>
            <service url="<YourService.js>" android:foregroundServiceType="mediaPlayback"/>
        </services>
    </android>
</ti:app>

See Google's ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK documentation for more details.

FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION

Numbersince 8.3.0read-only

Allows managing a media projection session for screen recording or taking screenshots while app is in the background.

This constant is passed to the Titanium.Android.Service.foregroundNotify method.

To use this constant, you must also set your <service/> element to the foregroundServiceType attribute value as shown below.

<ti:app>
    <android>
        <services>
            <service url="<YourService.js>" android:foregroundServiceType="mediaProjection"/>
        </services>
    </android>
</ti:app>

See Google's ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION documentation for more details.

FOREGROUND_SERVICE_TYPE_MICROPHONE

Numbersince 9.3.0read-only

Allows the microphone to be used while the app is in the background.

This constant is passed to the Titanium.Android.Service.foregroundNotify method.

To use this constant, you must also set your <service/> element to the foregroundServiceType attribute value as shown below.

<ti:app>
    <android>
        <services>
            <service url="<YourService.js>" android:foregroundServiceType="microphone"/>
        </services>
    </android>
</ti:app>

See Google's ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE documentation for more details.

FOREGROUND_SERVICE_TYPE_PHONE_CALL

Numbersince 8.3.0read-only

Allows ongoing phone call or video conferencing access while the app is in the background.

This constant is passed to the Titanium.Android.Service.foregroundNotify method.

To use this constant, you must also set your <service/> element to the foregroundServiceType attribute value as shown below.

<ti:app>
    <android>
        <services>
            <service url="<YourService.js>" android:foregroundServiceType="phoneCall"/>
        </services>
    </android>
</ti:app>

See Google's ServiceInfo.FOREGROUND_SERVICE_TYPE_PHONE_CALL documentation for more details.

RESULT_FIRST_USER

Numberread-only

Used with setResult to specify a user-defined result.

User-defined result constants values start at RESULT_FIRST_USER.

rootActivity

Titanium.Android.Activitysince 8.0.0read-only

The first activity launched by the application.

This is the main launcher activity defined in the "AndroidManifest.xml" which shows the splash screen. All windows opened are child activities below this root activity.

Closing this root activity via its finish() method will close all of its child activity windows as well and exit out of the app.

When resuming the app via a data intent such as a URL, notification, shortcut, etc. the root activity will fire a "newintent" event and update its intent property with the newly received intent.

START_NOT_STICKY

Numberread-only

A Service start mode indicating that if the host application is stopped by Android, the service should not be restarted automatically.

Use as a startMode value in the options object passed to createServiceIntent.

START_REDELIVER_INTENT

Numberread-only

A Service start mode indicating that if the host application is stopped by Android, the service should be restarted automatically and the original Intent re-sent.

Use as a startMode value in the options object passed to createServiceIntent.

TILE_STATE_ACTIVE

Numbersince 7.0.0read-only

QuickSettings tile is active.

The Tile is in enabled state and the user can interact with it.

TILE_STATE_INACTIVE

Numbersince 7.0.0read-only

QuickSettings tile is inactive.

The Tile is in disabled state, but the user can interact with it.

TILE_STATE_UNAVAILABLE

Numbersince 7.0.0read-only

QuickSettings tile is unavailable.

For some reason the Tile is not available to the user and will have no click action.

Methods 24

addEventListener

Inherited from Titanium.Proxy

Adds the specified callback as an event listener for the named event.

Parameters
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

Callback function to invoke when the event is fired.

4 fields
bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

createIntentChooser

Creates an activity chooser intent, used to allow the user to select a target activity for an intent.

Use this method when the user wants to take an action that could use any one of a number of applications. For example, when sending a plain text message, the user may choose to send a text message, send an email, or post to a social network.

You pass in an Intent representing the action being taken, and a title for the chooser.

The method returns another intent, representing the chooser, which can be used to start an activity. See the code example for details on how to display the chooser.

For more information, see the official Android documentation for Intent.ACTION_CHOOSER

Using a Chooser

The following example uses an activity chooser to send a plain text message.

var intent = Ti.Android.createIntent( {
    action: Ti.Android.ACTION_SEND,
    type: 'text/plain'
});
intent.putExtra(Ti.Android.EXTRA_SUBJECT, 'This is the subject.');
intent.putExtra(Ti.Android.EXTRA_TEXT, 'This is some text to send.')

var chooser = Ti.Android.createIntentChooser(intent, 'Send Message');
var activity = Ti.Android.currentActivity.startActivity(chooser);
Parameters
ParametersTypeDescription
intentTitanium.Android.Intent

The intent to display a chooser for.

titleString

Title to display on the chooser.

Returns Titanium.Android.Intent

createServiceIntent

Create an Intent to be used to start a service.

Parameters
ParametersTypeDescription
optionsServiceIntentOptions

Options for the Service.

2 fields
startMode? Number

One of the START_* constants from Titanium.Android to specify the "stickiness" of the Service when Android shuts down the host application.

url String

URL for the service's JavaScript.

Returns Titanium.Android.Intent

fireEvent

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

Parameters
ParametersTypeDescription
nameString

Name of the event.

event?Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

hasPermission

since 5.4.0

Returns true if the app has permission access.

Parameters
ParametersTypeDescription
permissionString | Array<String>

The permission to check for access. This can be any of the constants listed here with dangerous protection level here. For example, android.permission.WRITE_CONTACTS.

Since Titanium 6.1.0, the method will also accept Array[String](api:Global.String)

Returns Boolean

registerBroadcastReceiver

since 3.1.0

Registers broadcast receiver for the given actions.

Parameters
ParametersTypeDescription
broadcastReceiverTitanium.Android.BroadcastReceiver

The broadcast receiver to register and handle the broadcast.

actionsArray<String>

The actions that the broadcast receiver will handle

removeEventListener

Inherited from Titanium.Proxy

Removes the specified callback as an event listener for the named event.

Parameters
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

4 fields
bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

requestPermissions

since 5.4.0

Request for permission access.

Parameters
ParametersTypeDescription
permissionsString | Array<String>

The permission(s) to request for access. This can be any of the constants listed here with dangerous protection level here. Normal protection permissions are automatically enabled if they are included in the manifest. An example of a dangerous protection permission would be android.permission.WRITE_CONTACTS. The requested permission(s) MUST also be included in the Android Manifest.

Besides this, there are also requestPermission methods that are ready for commonly used situations. These methods are Titanium.Calendar.requestCalendarPermissions, Titanium.Contacts.requestContactsPermissions, Titanium.Filesystem.requestStoragePermissions, Titanium.Geolocation.requestLocationPermissions and Titanium.Media.requestCameraPermissions.

Since Titanium 6.1.0, the method will also accept a String. Any requests where permissions are already granted will yield a successful callback.

callback?Callback<RequestPermissionAccessResult>

Function to call upon user decision to grant access. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns Promise<RequestPermissionAccessResult>

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.