tiapp.xml and timodule.xml Reference

Introductions

The tiapp.xml file and its close cousin the timodule.xml file are XML configuration files that the Titanium SDK uses to generate native resources and code. Many of the configuration that lives in tiapp.xml is cross-platform, but some is platform-specific as well. The timodule.xml file is meant for custom Titanium Modules, and generally only contains platform-specific configuration.

Top level elements

These configuration elements live under the root <ti:app> tag of the tiapp.xml. Unless otherwise noted, the configuration value goes inside the tag's content, that is, <element> VALUE </element>.

guid

Required. A unique ID that associates this application for use in analytics and other Appcelerator Services. This value is generated by Appcelerator. Do not modify this value unless you know what you are doing.

id

Required. The application ID.

In Android, this ID is used to generate the package ID of the application, which must follow Java Package Naming Standards.

In iOS, this ID must match the Bundle ID when generating an Explicit App ID in the Apple Developer:Certificates, Identifiers & Profiles page.

name

Required. The application name. This is generally what is shown under the application icon on the end-user's mobile device.

analytics

Whether or not to automatically collect analytics for this application. Enabled by default. See Analytics Architecture.

copyright

The copyright of this application.

deployment-target

This element contains subelements of deployment targets used by Studio to determine which target options should be shown in the deployment menus.

• <target device="DEVICE"> : Specifies if the target device is supported by the project. Must be placed inside the <deployment-targets> element.

description

The description of this application.

fullscreen

Whether or not the application will start by taking up the entire screen and remove the status bar. Default is false.

icon

The application icon's filename. This file should be relative to the application's Resources directory, or alternatively, can also live under a platform-specific folder, such as Resources/iphone or Resources/android.

modules

This element includes subelements of modules to include with the project.

• <module platform="PLATFORM" version="MODULE_VERSION" deploy-type="DEPLOYMENT_ENVIRONMENTS"> : Defines a module to include with the project specified by the module's folder name or ZIP file minus the extension. The module should either be in the root level of the project (same level as the Resources folder) or in the <PATH_TO_TITANIUM_SDK>/modules folder. Must be placed inside the <modules> element.
  
  Define the platform attribute to specify which platforms to include the module with. Specify android for Android, commonjs for all platforms, or iphone for iPhone and iPad. Note that you can specify only one platform. For a module that may be included on several platforms, repeat the same module entry, specifying a different platform for each entry.
  
  Define the version attribute if you want to use a specific version of the module.
  
  Define the deploy-type attribute if you want to use the module in specific environments. To specify one or more environment, comma-separate the environment types. You may specify the following environments: development, test or production.
  
  
  
  
  
  

navbar-hidden

Whether or not the navigation bar is hidden for this application. Default is false.

On Android, this will remove the top action/title bar.

plugins

This element includes subelements of plugins to include with the project.

• <plugin version="PLUGIN_VERSION"> : Defines a plugin to include with the project specified by the plugin's folder name. Place plugins in the plugins folder of the project (same level as the Resources folder). This element must be placed inside the <plugins> element. The version attribute is optional. Define it to include a specific version of the plugin.

property

See Application properties below.

publisher

The publisher of this application.

statusbar-hidden

Only supported on Android. Will remove the top status bar if set true. Default is false.

sdk-version

Specifies the SDK to build against or use for CLI commands.

url

The URL of this application.

version

The application version.

For iOS the version number is truncated to three dot-separated numbers. For example, '2.1' remains as '2.1', but '2.1.0.1' will be converted to '2.1.0'.

Deprecated elements

• <persistent-wifi> : See UIRequiresPersistentWiFiUIRequiresPersistentWiFi.
• <prerendered-icon> : See UIPrerenderedIcon.
• <statusbar-style> : See UIStatusBarStyle.
• <statusbar-hidden> : See UIStatusBarHidden.

Application properties

tiapp.xml also supports ad-hoc properties that can be used by the application with Titanium.App.Properties. These properties must be placed inside the root <ti:app> element.

Properties generally follow the form:

• name is the property name
• type is the property value's type, valid values are: string, bool, int, double
• value is the property's value

Properties are also used in specific cases by each platform, which is further explained in each platform section.

ti.ui.defaultunit

The special property ti.ui.defaultunit can be used to set the default unit used for specifying sizes and positions.

The default unit can be one of the following:

• system . Specifies system default unit.
• cm . Centimeters.
• dip or dp . Density-independent pixels (DIPs).
• in . Inches.
• mm . Millimeters.
• px . Pixels.

Setting the default unit to pixels may cause issues on iOS unless you detect and handle Retina displays in your code.

See Ti.UI.View in the Titanium SDK API Reference for more information on units.

intent-filter-new-task

Since launch modes cannot be used with Titanium Android, to offer similar behavior to android:launchMode="singleTask" when using intent filters, you can set the intent-filter-new-task property in your tiapp.xml:

This will start any activity launched from an intent filter as a new task.

appc-security-jailbreak-detect

The special property appc-security-jailbreak-detect can be used to increase the security of your application by preventing the mobile app from running on a Jailbroken (iOS) or rooted (Android) device.

This feature is disabled by default. If you enable this feature, you will be required to set the property of remote for appc-sourcecode-encryption-policy in order for it to work. Note: there is no default behavior for appc_sourcecode-encryption-policy. You must explicitly set this value.

Setting this property to false will allow your application to run on devices that have been jailbroken or rooted.

appc-security-debugger-detect

The special property appc-security-debugger-detect can be used to increase the security of your application by preventing debugging applications from connecting to your mobile app.

This feature is disabled by default. If you enable this feature, you will be required to set the property of remote for appc-sourcecode-encryption-policy in order for it to work. Note: there is no default behavior for appc_sourcecode-encryption-policy. You must explicitly set this value.

Setting this property to false will allow debug applications to connect to your mobile app.

appc-sourcecode-encryption-policy

The special property appc-sourcecode-encryption-policy determines the encryption policy for application assets. Values can be:

• embed: Embeds theencryption key and initialization vector (IV) into the application binary. The key and IV are padded and obfuscated.
• remote: Stores the encryption key remotely, which requires the device to have an internet connection to run the application(default behavior).

Android-specific section

Under the top <ti:app> element, you may optionally have an <android> element that contains Android specific configuration. If the application requires any ad-hoc XML from AndroidManifest.xml, make sure to also add the android XML namespace, as shown in the example below. The official Android Developers website describes all the other elements that are supported, such as <service> , <uses-permission> and <activity> for instance, and these will be added using the same logic.

The above example includes all of the common sections to show the structure of the XML elements. All of these sections are optional, and are described below:

abi

Selects the target ABI architecture. Only used when building for the V8 runtime. Choose betweenthe following values:

• all (All architectures, default)
• arm64-v8a
• armeabi-v7a
• x86
• x86_64

Targeting an ABI architecture will help reduce the application and APK size, but will support fewer devices. Currently defaults to 'all'. You can upload multiple APK's for multiple ABI's, improving the file size of the bundled app.

activities

Defines a list of custom JavaScript-based Android activities. This is a custom Titanium XML element and should not be confused with the Android Manifest activity element.

• <activity url="activity.js"/> : Creates an activity with a URL that points to the JavaScript file (under Resources) that defines it.
• Ad-hoc elements: Inside the <activity> element, any ad-hoc element from an AndroidManifest.xml is supported. See the documentation for the activity element in AndroidManifest.xml.

manifest

Ad-hoc XML from AndroidManifest.xml. Some common elements to set are listed below:

application

This element contains subelements that declare each of the application's components and has attributes that can affect all the components. Must be placed inside the <manifest> element. See the documentation for the application element in AndroidManifest.xml.

uses-permission

Request a permission for the application to use. Must be placed inside the <manifest> element.See the "Setting calendar permissions" example below andthe documentation for the uses-permission element in AndroidManifest.xml.

uses-sdk

Lets you express an application's compatibility with one or more versions of the Android platform, by means of an API Level integer. Must be placed inside the <manifest> element.See the "Set a target or minimum SDK level" example belowandthe documentation for the uses-sdk element in AndroidManifest.xml.

services

Defines a list of custom JavaScript-based Android services (long running background processes).This is a custom Titanium XML element and should not be confused with the Android Manifest service element.

• <service url="service.js" type="standard"/> : Creates a service with a URL that points to the JavaScript file (under Resources) that defines it. type is optional.
• Ad-hoc elements: Under the <service> tag, any ad-hoc element from an AndroidManifest.xml is supported. See the documentation for the service element in AndroidManifest.xml.

Android-specific application properties

Android also supports a number of application properties for various internal settings. (See Application properties above on how to define an application property.)

Properties to work around Android bugs 2373 and 5277

See TIMOB-4941, TIMOB-1559 and TIMOB-9285 for information about the Titanium workaround to Google issues 2373 and 5277. TIMOB-9285 in particular has a useful explanation of the issue and of ti.android.bug2373.finishfalseroot, the newest of the properties listed below.

Common requirements

Set a target or minimum SDK level

To indicate that your application supports a certain API Level, add the <uses-sdk> element with the android:minSdkVersion and/or android:targetSdkVersion attributes. It may be necessary to set these attributes to enable certain Android features, such as the action bar or theme. Note that the API Level you enter below must be within the min and max supported levels the Titanium SDK supports as shown in the Titanium Compatibility Matrix.

Configuring screen densities

To indicate that your application supports any screen densities, which is a common use-case, add the <supports-screens> element and set the screen size attributes to true:

Enabling the debugger by default

To make the app debuggable by default, set the <application> attribute to true (it's false in our default manifest template).
This setting is required to attach the Java debugger to a running application. It is not required for debugging the application's JavaScript inStudio, so setting debuggable to true may be primarily interesting to developers working on native Android modules or debugging issues in the Titanium native libraries.

Setting install location preferences

Your Android apps are installed by default to the device's internal storage, but Titanium apps can be installed to the SD card using the following configuration:

For the android:installLocation property, choose one of these values:

• android:installLocation="preferExternal" -- specifies that you prefer your app to install to the SD card, but if one isn't present the app can be installed to internal storage.
• android:installLocation="auto"– specifies that the phone's configuration will determine the installation location. Generally, your app will be installed to internal storage if sufficient space is available. In that case, users could still move your app by opening Settings > Applications > Manage applications, tapping your app, and tapping Move to SD card.
• android:installLocation="internalOnly"– which specifies that your app cannot be installed to the SD card. See the Android docs for the various reasons why you might choose this option.

Finally, you need to add the <uses-sdk> tag within the <manifest> node. This tag specifies that your app requires Google's version 7 or newer APIs — in other words, the phone must be running Android 2.1 Update 1 or newer. That pretty much covers all the newer phones, but will exclude some older devices. On those phones, your app will install to the internal storage.

Requesting a large heap from Dalvik

To request a large heap size, set the android:largeHeap property of the <application> attribute to true. Requires API level11 or higher. Note that you are not guaranteeda fixed increase in available memory, because some devices are constrained by their total available memory.

iOS-specific section

Under the top <ti:app> element, you may optionally have iOS-specific elements.

team-id

Since Release 5.0.0. Specifies the team ID to be used as a prefix for the app-id. This property is required when using app extensions (e.g. share extensions, watch extensions and siri extentions).

Since Release 6.1.0. Specifies the target's entitlements injected into the generated native project.

Prior to this release, developers could already specify entitlements by using the "Entitlements.plist" in the project root that is merged with the internal entitlements (e.g. push-notifications). Starting in Titanium 6.1.0, developers can also specify entitlements in the central "tiapp.xml" project file. It will be merged with internal entitlements and is able to override existing entitlements keys.

extensions

Since Release 5.0.0. Specifies the iOS extensions the applications supports.

For each extension, add an <extension> element and set the projectPath attribute to the relative or absolute path to the Xcode project folder (<name>.xcodeproj).

In the extension element, add a <target> element and set the name attribute to the target name of the extension. For Apple Watch applications, you will need to add another target element for the WatchApp target.

In the target element, add a <provisioning-profiles> element, which determines the devices the application can run on. Add the following elements as children of the provisioning-profiles element. For each listed element you add, set the node text to the provisioning profile UUID of the extension or watch application:

• <devices/> : Add to deploy for development builds
• <dist-appstore/> : Add to deploy to the iTunes App Store
• <dist-adhoc/> : Add to deploy for ad-hoc builds

min-ios-ver

Specifies the minimum iOS version supported by this application. The default value when not specified is "9.0".

min-sdk-ver

Specifies the minimum SDK (Xcode) version supported by this application.The default value when not specified is "8.0".

plist

The <ios> section allows you to define settings to add to the generated Info.plist file. These values take the form of key/value pairs, defined using the same syntax as the Info.plist file.

You can include a custom Info.plist file in the top-level directory of your Titanium project, but these value are overwritten by the settings in the <plist> section of the tiapp.xml file.

For a detailed description of all Info.plist keys, see the iOS Info.plist Key Reference on the iOS Developer Center.

You can specify device-specific configurations by appending ~ipad, ~iphone or ~ipod to the key name, just as in theInfo.plistfile. For example:

Not all keys are supported at this time. See Unsupported Info.plist Keys for a list of keys that may not be overridden in the tiapp.xml file.

Some notable keys are listed in the following sections.

UISupportedInterfaceOrientations

Specifies which interface orientations this application supports.

Replaces <orientations> .

For device-specific configurations, use:

• UISupportedInterfaceOrientations~ipad
• UISupportedInterfaceOrientations~iphone
• UISupportedInterfaceOrientations~ipod



  

UIBackgroundModes

A list of background modes this app supports. For a BackgroundService to run for more than a limited period of time, the application must declare one or more of these background modes.

Replaces <backgroundModes> .

UIRequiredDeviceCapabilities

A list of features this app requires.

Replaces <requires> .

UIRequiresPersistentWiFi

Specifies whether this app requires a Wi-Fi connection.

Replaces the top-level <persistent-wifi> element.

Example:

Also, the following iOS-only top-level elements will be deprecated:

UIPrerenderedIcon

Specifies whether the app’s icon already includes a shine effect.

Replaces the top-level <prerendered-icon> element.

UIStatusBarHidden

Specifies whether the status bar is initially hidden when the app launches.

Replaces the top-level <statusbar-hidden> element.

UIStatusBarStyle

Specifies the style of the status bar as the app launches.

Replaces the top-level <statusbar-style> element.

Unsupported Info.plist keys

The following Info.plist properties are ignored in the <plist> section. The values for these properties are automatically generated by Titanium and may not be overridden in the tiapp.xml file or custom Info.plist file.

• CFBundleDisplayName. The name in the generated file always reflects the value of the <name> element
• CFBundleExecutable
• CFBundleIconFile
• CFBundleIconFiles. Automatically includes all application icon files from project directory.
• CFBundleIdentifier
• CFBundleInfoDictionaryVersion
• CFBundleName
• CFBundlePackageType
• CFBundleSignature
• CFBundleVersion (until Titanium 4.1.0)
• CFBundleShortVersionString(until Titanium 4.1.0)

iOS9 Security and canOpenUrl

With some of the new security features of iOS9, SDK 5.1.2's canOpenUrl might fail without adding in the proper properties in the info.plist file. For example,

run-on-main-thread

Since Release 5.1.0. Enables running all JavaScript scripts on the main thread as opposed to a secondary thread. It is disabled by default in existing projects and enabled in new projects.It will be enabled automatically in Titanium SDK 7.0.0 and later.

log-server-port

Since Release 6.0.0. Specifies a custom port to use for the iOS log-server. Use this when the default port is causing issues like "Trying to connect to log server port xxxxx ...".

allow-custom-keyboards

Since Release 6.1.0. Allow or disallow custom iOS 8+ keyboard extensions. By default, custom keyboard extensions are allowed. Add this property and set it to false to disallow custom keyboard extensions.

use-app-thinning

Since Release 5.1.0. Determines whether to enable App Thinning for iOS applications by using an Asset Catalog. An Asset Catalog contains image assets for specific devices. When a user installs your application, only the resources that your device supports will be downloaded. The element is automatically added to new projects since Release 5.1.0. For details, see App Thinning: Slicing.

use-autolayout

Since Release 5.1.0. Enables the iOS auto-layout engine to layout the children components of a view. Disabled by default.

use-jscore-framework

Since Release 4.1.0. Use the built-in JavaScriptCore framework rather than the custom Titanium one. It will be made default in Titanium SDK 7.0.0 and later.

Legacy iPhone

Prior to release 2.1, iOS-specific settings were contained in an <iphone> element. These settings are deprecated and should be replaced with the corresponding iOS settings listed in the iOS specific section. It will be removed in Titanium SDK 7.0.0 and later.

• <orientations device="device"> : Restricts the device to these orientations when the application is running. The value of "device" can be "iphone", or "ipad". Deprecated in Release 2.1, use UISupportedInterfaceOrientations instead.
  
  • <orientation> : An orientation for this <orientations> list, valid values are: Ti.UI.PORTRAIT, Ti.UI.UPSIDE_PORTRAIT, Ti.UI.LANDSCAPE_LEFT, Ti.UI.LANDSCAPE_RIGHT.
• <backgroundModes> : A list of background modes this app supports. Deprecated in Release 2.1, use UIBackgroundModes instead.
  For a BackgroundService to run for more than a limited period of time, the application must include the <backgroundModes> element in tiapp.xml.
  
  • <mode> : A background mode, valid values are: audio, location, and voip.
• <requires> : A list of features this app requires. Deprecated in Release 2.1, use UIRequiredDeviceCapabilitiesinstead.
  
  • <feature> : A feature that this app requires, valid values are: telephony, wifi, sms, still-camera, auto-focus-camera, front-facing-camera, camera-flash, video-camera, accelerometer, gyroscope, location-services, gps, magnetometer, gamekit, microphone, opengles-1, opengles-2, armv6, armv7, peer-peer
  
  

Windows-specific

Under the top <ti:app> element, you may optionally have a <windows> element that contains Windows-specific configuration settings.

id

Since Release 5.1.0. Set to the Package/Identity/Name of the application, which was generated when you created the application in the Windows Dev Center Dashboard. Required to package the application. Microsoft will validate this field when you submit the package to the Windows Store.

manifest

Add the <manifest> element as a child of the <windows> element to include ad-hoc Windows appx.manifest XML elements. You may optionally define the target attribute and set it to either phone or store to have Windows Phone or Windows Store specific manifests, respectively.

Only supports the following elements:

• <Capabilities> : for a list of capabilities, see Window Dev Center: App capability declarations
• <Prerequisites>
• <Properties>
• <Resources>
• <Extensions>

Add capabilities

Some Titanium features require capability definitions in order for them to function. These can be defined in the tiapp.xml under the platform specific <windows> tag.

Users can generate capabilities even if they are not defined in the tiapp.xml file. For example, if app.js includes a capabilitybut it's not listed as a capability in the tiapp.xml:

app.js :

tiapp.xml :

And you build the app with this command: appc run -p windows -S 10.0 --build-only

The result should be this:

When building a Windows platform module that requires specific capabilities, the user can use timodule.xml the same way Android modules requires specific capabilities. At build time, these required capabilities will be included in the user's app.

For example, when building an app that has the following capability in the timodule.xml:

Once the app has been built, you should see that the timodule.xml was updated to look something like this:

Internet capability

Enabled by default, required for Titanium.Network.*

Location capability

Required for Titanium.Geolocation

Background audio capability

Required for Titanium.Media.AudioPlayer background audio functionality

Audio recorder

Required for Titanium.Media.AudioRecorder functionality

Photo gallery

Required for Titanium.Media.openPhotoGallery functionality

Capabilities can also be set independently for store or phone applications by specifying the target.

For more information regarding Windows App capabilities refer to https://msdn.microsoft.com/en-us/library/windows/apps/hh464936.aspx

Target Windows version

Users can define a target Windows version by configuring the tiapp.xml in the same way one can configure iOS and Android target versions:

Handling differing capabilities between Windows 8.1 and 10

Windows Phone 8.1:

Windows 8.1 Store

Windows 10 is universal so target doesn't matter:

Common capabilities across targets and SDK versions (Windows 10, Windows 8.1 Store, and Windows 8.1 Phone):

Windows-specific application properties

Cloud

Mobile Backend Services uses the following Application properties to configure a Titanium project to use Mobile Backend Services. If a deployment-specific setting is provided (production or development) then that value will be used for the current deployment environment. To specify a deployment-specific settings add the suffix -development or -production to the property name, for example, acs-api-key-development and acs-api-key-productions are the deployment-specific settings for acs-api-key.

Google Play Services

As of Titanium 9.0.0, if your Android app includes the ti.playservices module, it will automatically check on app startup if Google Play Services is installed on the device and is up-to-date. If not, it will request the end-user to install or update it before executing the app's main script. This is needed so that the Google Play Services libraries included in the app can function. If you want to disable this feature, then you can do so by setting the following tiapp.xml property to false.

Modules

See the Module Developer Guides for Android and iOS.

timodule.xml

A timodule.xml follows the same structure as a tiapp.xml, but most of the metadata for a module project lives in the module's manifest file. Right now, the timodule.xml is only used in Android, and it supports all of the tags listed in the Android section above. Any custom metadata your Android module defines in it's timodule.xml <android> section will automatically be merged with a Titanium application that installs your module.

In some cases, metadata defined in the timodule.xml file depends on application-specific metadata from the tiapp.xml file. For example, if the module defines a custom permission, or a custom intent filter, you may need to include the application's package name in the identifier.

To support this use case, the timodule.xml file allows token substitution, so you can specify variable values that will be replaced with application-specific values at build time. For example:

Note the token ${tiapp.properties['id']}. In this token, tiapp.properties refers to the collection of top-level properties defined in the
tiapp.xml file. To access a property in this collection, such as <id>, <name>, <version>, or <publisher>, use square brackets with the property name in quotes inside, as shown in the example.

If you include this module in an application with the App ID com.example.app, the AndroidManifest.xml file is generated with the following permission element: