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.

Example: tiapp.xml
<ti:app xmlns:ti="http://ti.appcelerator.org">
    <id>com.appcelerator.helloWorld</id>
    <name>helloWorld</name>
    <version>1.0.1</version>
    <icon>appicon.png</icon>
    <fullscreen>false</fullscreen>
    <navbar-hidden>false</navbar-hidden>
    <analytics>true</analytics>
    <guid>GUID</guid>
	<ios>
        <plist>
            <dict>
		        <key>UISupportedInterfaceOrientations~iphone</key>
                <array>
			        <string>Ti.UI.PORTRAIT</string>
		        </array>
		        <key>UISupportedInterfaceOrientations~ipad</key>
                <array>
			        <string>Ti.UI.PORTRAIT</string>
			        <string>Ti.UI.UPSIDE_PORTRAIT</string>
			        <string>Ti.UI.LANDSCAPE_LEFT</string>
			        <string>Ti.UI.LANDSCAPE_RIGHT</string>
		        </array>
            </dict>
        </plist>
	</ios>
	<android xmlns:android="http://schemas.android.com/apk/res/android">
        <tool-api-level>10</tool-api-level>
        <abi>all</abi>
	</android>
    <mobileweb>
        <splash>
            <enabled>true</enabled>
            <inline-css-images>true</inline-css-images>
        </splash>
        <theme>default</theme>
    </mobileweb>
	<modules/>
</ti:app>

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.

Example
<id>com.bluthcompany.fakeblock</id>

name

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

Example
<name>Fakeblock</name>
Icon

On Android, if you change the name to a value that starts with a digit, you need to prefix the name in the activity with an undersore (_) if you include activities in the Android section of the tiapp.xml file. For example, if you change the name to 2Foo the activity name will be _2Foo.

 

analytics

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

Example: Enable Ti.Analytics
<analytics>true</analytics>

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.
Example: Specify the project only supports Android targets
<deployment-targets>
    <target device="android">true</target>
    <target device="ipad">false</target>
    <target device="iphone">false</target>
    <target device="mobileweb">false</target>
</deployment-targets>

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.

Sample code:

 

<windows>
     <TargetPlatformVersion>10.0.14393.0</TargetPlatformVersion>
     <TargetPlatformMinVersion>10.0.10240.0</TargetPlatformMinVersion>
</windows>

 

description

The description of this application.

<description>Tap to rock out with this block.</description>

fullscreen

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

Since Release 5.0.0, on Android, the theme will be set to Theme.AppCompat.NoTitleBar.Fullscreen.

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.

Example: Default icon in ./Resources or ./Resource/<platform>
<icon>appicon.png</icon> 

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: developmenttest or production.
Example: Include the ti.cloud module
<modules>
    <module platform="commonjs">ti.cloud</module>
    <module platform="android" deploy-type="development,test">junit</module>
</modules>

navbar-hidden

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

Supported since Release 5.0.0 for Android. On Android, the theme will be set to Theme.AppCompat.NoTitleBar unless fullscreen or statusbar-hidden is set to true.

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.
Example: Include the Alloy plugin
<plugins>
    <plugin version="1.0">ti.alloy</plugin>
</plugins>

property

See Application properties below.

publisher

The publisher of this application.

Example
<publisher>Bluth Company</publisher>

statusbar-hidden

Only supported on Android.  Set to true to set the theme to Theme.AppCompat.NoTitleBar.Fullscreen. Default is false.

sdk-version

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

Example: Use Titanium SDK 3.2.0 GA
<sdk-version>3.2.0.GA</sdk-version>

url

The URL of this application.

Example
<url>http://www.bluthcompany.com/fakeblock</url>

version

The application version.

Since Release 3.3.0, 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'. 

Prior to Release 3.3.0, for the iOS platform, the version number will be converted to three dot-separated numbers according to Apple's CFBundleShortVersionString and CFBundleVersion when creating a package.  For example, if you specify '2.1' or '2.1.0.1', the version number will be converted to '2.1.0' for the final package.

Example
<version>3.1.4</version>

Deprecated Elements

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.

Icon

As of Release 3.2.0, any properties defined inside the tiapp.xml are read-only. Previously, you could overwrite these property values.

Properties generally follow the form:

<property name="name" type="type">value</property>
  • name is the property name
  • type is the property value's type, valid values are: stringboolintdouble
  • 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.

<property name="ti.ui.defaultunit">system</property>

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.

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.

<property name="appc-security-jailbreak-detect">true</property>

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.

<property name="appc-security-debugger-detect">true</property>

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 the encryption 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). 
<property name="appc-sourcecode-encryption-policy">remote</property>

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.

<android xmlns:android="http://schemas.android.com/apk/res/android">
  <!-- Custom Titanium elements -->
  <abi>all</abi>
  <activities>
    <activity url="activity.js"/>
  </activities>
  <services>
    <service url="service.js" type="standard"/>
  </services>
  <!-- Android Manifest element -->
  <manifest>
    <uses-sdk android:minSdkVersion="10" android:targetSdkVersion="14"/>
    <application>
        <activity>...</activity>
        <service>...</service>
    </application>
  </manifest>
</android>

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 between 'armeabi' for ARM-based devices that support at least ARMv5TE, 'armeabi-v7a' for ARMv7-based devices or 'all' for all supported devices. Targeting an ABI architecture will help reduce the application and APK size, but will support fewer devices. Available in Titanium SDK 2.1.3 and later. Currently defaults to 'all'.

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 and the 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 below and the 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.

tool-api-level

Deprecated since Release 3.2. The version of the Android API that Titanium builds against. Currently defaults to the newest version of the Android SDK you have installed.  To set a target SDK version, see Set a target or minimum SDK level.

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.)

Property Name

Type

Default Value

Description

ti.android.shake.factor

double

1.3

Shake factor used for the "shake" event in the Titanium.Gesture module

ti.android.shake.quiet.milliseconds

int

500

Number of "quiet" milliseconds before the "shake" event is fired

ti.android.shake.active.milliseconds

int

1000

Number of "active" milliseconds before the "shake" event is fired

ti.android.google.map.api.key.development

string

N/A

Deprecated. Google Maps v1 API Key for use in development.

ti.android.google.map.api.key.production

string

N/A

Deprecated. Google Maps v1 API Key for use in production.

ti.android.httpclient.maxbuffersize

int

524288

The maximum buffer size (in bytes) before an HTTP response is written to a temporary file instead of memory (default is 512KB)

ti.android.threadstacksize

int

16384

Deprecated since Release 3.0.0.  This setting is only useful with Rhino. The stack size (in bytes) to use when creating a Javascript thread (default: 16KB). Bump larger when encountering StackOverflow errors in very large Javascript files

ti.android.compilejs

bool

N/A

Turns on or off JS compilation. By default, JS compilation is only on when distributing an application, but manually setting this to "true" will enable it for development as well.

ti.android.debug

bool

false

Turn on detailed logging in the SDK

ti.android.root.reappears.restart bool false Restarts the application if the root task was destroyed by Android after a period of inactivity.

ti.android.runtime

string

v8

Deprecated since Release 3.0.0. Titanium applications only support the V8 runtime since 3.0.0. 'v8' or 'rhino' (since 1.8.0)

ti.android.useLegacyWindow bool false Not supported since Release 3.3.0. Enables or disables the legacy window behavior that a heavyweight window is created if any of the following properties are defined on creation: fullscreen, navBarHidden, modal, or windowSoftInputMode. By default, the legacy behavior is disabled, which means all the windows are heavyweight. (since 3.2.0)
Example: Disable Fastdev
<property name="ti.android.fastdev">false</property>

Properties to work around Android bugs 2373 and 5277

See TIMOB-4941TIMOB-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.

Property Name

Type

Default Value

Description

ti.android.bug2373.finishfalseroot

bool

true (since Release 3.2.0)

false (prior to Release 3.2.0)

(New since Titanium SDK 2.1.2.) Setting to true will avoid showing any messages to the user and will force any subsequent, anomalous instantiations of the application's launch Activity to finish and disappear without disturbing the user. This is explained in greater detail in JIRA issue TIMOB-9285. This property should be used by itself, without any of the other "bug2373" properties. It is the least intrusive of these properties and should give the best user experience.

ti.android.bug2373.disableDetection

bool

false

setting to true will completely disable the workaround

ti.android.bug2373.title

String

Restart Required

title of dialog

ti.android.bug2373.message

String

An application restart is required

message used in dialog. if skipAlert is true the message is shown in a Toast if message length is > 0

ti.android.bug2373.buttonText

String

Continue

button text on alert dialog

ti.android.bug2373.restartDelay

int

500

number of milliseconds to wait before starting the new copy of the app with the correct Intent settings.

ti.android.bug2373.finishDelay

int

0

number of milliseconds to wait before finishing (exiting) the current application.

ti.android.bug2373.skipAlert

bool

false

if true, the dialog box will not be shown, but the workaround will still be applied if disableDetection is false.

Common Requirements

Set a target or minimum SDK level

Icon

Starting with Release 4.0.0, due to the addition of material theme support, the android:targetSDKVersion attribute must be set to at least 21 or higher, and the android:minSdkVersion attribute must be set to at least 14 or higher.

Prior to Release 4.0.0 and starting with Release 3.3.0, due to the addition of the appcompat library, the android:targetSDKVersion attribute must be set to at least 14 or higher, and the android:minSdkVersion attribute must be set to at least 10 or higher.

If not, the build will fail with a "Failed to package application" error.

To indicate that your application supports a certain SDK 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.

<android xmlns:android="http://schemas.android.com/apk/res/android">
    <manifest>
        <uses-sdk android:minSdkVersion="14" android:targetSdkVersion="21"/>
    </manifest>
</android>

In the previous example, the following settings indicate that the application can run on Android 4.x, but was targeted and tested for Android 5.x.

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:

<android xmlns:android="http://schemas.android.com/apk/res/android">
    <manifest>
        <supports-screens
            android:smallScreens="true"
            android:normalScreens="true"
            android:largeScreens="true"
            android:xlargeScreens="true"
        />
    </manifest>
</android>
Icon

Do not set the android:anyDensity attribute to false. Google does not recommend changing the default value. Setting this attribute to false may cause undesired behavior.

 

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 in Studio, so setting debuggable to true may be primarily interesting to developers working on native Android modules or debugging issues in the Titanium native libraries.

<android xmlns:android="http://schemas.android.com/apk/res/android">
    <manifest>
        <application android:debuggable="true" />
    </manifest>
</android>

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:

<android xmlns:android="http://schemas.android.com/apk/res/android">
   <manifest android:installLocation="preferExternal">
      <uses-sdk android:minSdkVersion="7" />
   </manifest>
</android>

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 on Android 3.x and later, set the android:largeHeap property of the <application> attribute to true. Requires API level 11 or higher.  Note that you are not guaranteed a fixed increase in available memory, because some devices are constrained by their total available memory.

<android xmlns:android="http://schemas.android.com/apk/res/android">
    <manifest>
        <application android:largeHeap="true"/>
    </manifest>
</android>


iOS-specific section

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

<ti:app>
    <ios>
        <entitlements>
			<dict>
				<!-- Enter entitlements like com.apple.security.application-groups -->
			</dict>
        <extensions>
            ...
        </extensions>
        <plist>
            <dict>
                <!-- Enter Info.plist entries like UIStatusBarStyle -->
            </dict>
        </plist>
        <use-autolayout>true</use-autolayout>
    </ios>
</ti:app>

entitlements

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.

Example: Enable app-groups for app-extensions
<ti:app>
  <ios>
    <entitlements>
      <dict>
        <!-- Example: Enable app-groups for app-extensions -->
      	<key>com.apple.security.application-groups</key>
       	<array>
          <string>group.com.appcelerator.mycoolapp</string>
        </array>
      </dict>
    </entitlements>
  <ios>
</ti:app>

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

Example: Include watchOS extensions
<ti:app>
  <ios>
    <extensions>
      <extension projectPath="extensions/foo/foo.xcodeproj">
        <target name="foo WatchApp Extension">
          <provisioning-profiles>
            <devices/>
            <dist-appstore/>
            <dist-adhoc/>
          </provisioning-profiles>
        </target>
        <target name="foo WatchApp">
          <provisioning-profiles>
            <devices/>
            <dist-appstore/>
            <dist-adhoc/>
          </provisioning-profiles>
        </target> 
      </extension>
    </extensions>
  <ios>
</ti:app>

min-ios-ver

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

 

Example: Set 9.0 as the minimum iOS version
<ios>
    <!-- Require iOS 8.2 or later -->
    <min-ios-ver>8.2</min-ios-ver>
</ios>

min-sdk-ver

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

Example: Set Xcode 4.3 as the minimum SDK version
<ios>
    <!-- Require Xcode 9 or later -->
    <min-sdk-ver>9.0</min-sdk-ver>
</ios>

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 the Info.plist file. For example:

<key>UISupportedInterfaceOrientations~ipad</key>

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

Example: Limits iPhone orientation to portait and no limits for iPad
<ios>
<plist>
<dict>
  <key>UISupportedInterfaceOrientations~iphone</key>
  <array>
    <string>UIInterfaceOrientationPortrait</string>
  </array>
  <key>UISupportedInterfaceOrientations~ipad</key>
  <array>
    <string>UIInterfaceOrientationPortrait</string>
    <string>UIInterfaceOrientationPortraitUpsideDown</string>
    <string>UIInterfaceOrientationLandscapeLeft</string>
    <string>UIInterfaceOrientationLandscapeRight</string>
  </array>
</dict>
</plist>
</ios>

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>.

Example: Enables all background services
<ios>
<plist>
<dict>
  <key>UIBackgroundModes</key>
  <array>
    <string>audio</string>
    <string>location</string>
    <string>voip</string>
    <string>newsstand-content</string>
    <string>external-accessory</string>
    <string>bluetooth-central</string>
    <string>bluetooth-peripheral</string>
  </array>
</dict>
</plist>
</ios>

UIRequiredDeviceCapabilities

A list of features this app requires.

Replaces <requires>.

Example: Require all device capabilities
<ios>
<plist>
<dict>
  <key>UIRequiredDeviceCapabilities</key>
  <array>
    <string>telephony</string>
    <string>wifi</string>
    <string>sms</string>
    <string>still-camera</string>
    <string>auto-focus-camera</string>
    <string>front-facing-camera</string>
    <string>camera-flash</string>
    <string>video-camera</string>
    <string>accelerometer</string>
    <string>gyroscope</string>
    <string>location-services</string>
    <string>gps</string>
    <string>magnetometer</string>
    <string>gamekit</string>
    <string>microphone</string>
    <string>opengles-1</string>
    <string>opengles-2</string>
    <string>armv6</string>
    <string>armv7</string>
    <string>peer-peer</string>
    <string>bluetooth-le</string>
  </array>
</dict>
</plist>
</ios>

UIRequiresPersistentWiFi

Specifies whether this app requires a Wi-Fi connection.

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

Example:

<key>UIRequiresPersistentWiFi</key><true/>

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.

Example
<key>UIPrerenderedIcon</key><true/>

UIStatusBarHidden

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

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

Example: Hide the status bar
<key>UIStatusBarHidden</key><true/>

UIStatusBarStyle

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

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

Example: Use the tranluscent style
<key>UIStatusBarStyle</key><string>UIStatusBarStyleBlackTranslucent</string>

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, 

<key>LSApplicationQueriesSchemes</key>
    <array>
        <string>fbapi</string>
        <string>fbauth2</string>
        <string>fbshareextension</string>
        <string>fb-messenger-api</string>
        <string>twitter</string>
        <string>whatsapp</string>
        <string>instagram</string>
        <string>comgooglemaps</string>
    </array>

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.

<ti:app>
    <property name="run-on-main-thread" type="bool">true</property>
</ti:app>

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 ...".

<ti:app>
    <ios>
		<!-- Or any other available port -->
        <log-server-port>27973</log-server>
    </ios>
</ti:app>

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.

<ti:app>
    <property name="allow-custom-keyboards" type="bool">false</property>
</ti:app>

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.

Filesystem Access

Icon

Because images are store in the Asset Catalog, reading image files manually from the filesystem should be done using the Ti.Filesystem.getAsset() method. 

<ti:app>
    <ios>
         <use-app-thinning>true</use-app-thinning>
    </ios>
</ti:app>

use-autolayout

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

Experimental Feature

Icon

This is an experimental feature with known issues:

If you find any issue using this feature, file a bug in JIRA.

<ti:app>
    <ios>
        <use-autolayout>true</use-autolayout>
    </ios>
</ti:app>

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.

<ti:app>
    <ios>
        <use-jscore-framework>true</use-jscore-framework>
    </ios>
</ti:app>


Legacy iPhone section

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.PORTRAITTi.UI.UPSIDE_PORTRAITTi.UI.LANDSCAPE_LEFTTi.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: audiolocation, 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: telephonywifismsstill-cameraauto-focus-camerafront-facing-cameracamera-flashvideo-cameraaccelerometergyroscopelocation-servicesgpsmagnetometergamekitmicrophoneopengles-1opengles-2armv6armv7peer-peer

Mobile-Web-specific section

Under the top <ti:app> element, you may optionally have a <mobileweb> element that contains a Mobile-Web-specific configuration.

analytics

Define analytics-related settings. Only one setting is currently supported.

  • <use-xhr>: Defaults to false. When value is false, analytics data is sent using an iframe. When value is true, analytics data is sent using XMLHttpRequest (XHR). The default iframe method is the most robust method, though it can interfere with the history of WebViews. XHR doesn't interfere with WebViews, but only works on newer browsers that support Cross-Origin Resource Sharing (CORS).

disable_error_screen

If true, the error screen is disabled and errors are logged to the browser's debug console. If the error screen is enabled, the error message may or may not be displayed in the debug console depending on the web browser. Setting this to true may provide more detailed information that the message printed to the error screen. Note that this setting only applies when running in development mode. In production mode, the error screen is always disabled.

filesystem

File system-related settings.

  • <backend>: Selects a filesystem implementation. Ti/_/Filesystem/Local is the only value currently supported and stores data in the web browser's local storage.
  • <registry>: Set to lazy to load filesystem registry information as needed. This is the default. If you are using the filesystem, set this value to preload to improve response time at the expense of somewhat larger initial download.

map

Map-related settings.

  • <apikey>: This value is optional for Mobile Web.
  • <backend>Ti/_/Map/Google is the only value currently supported.

precache

Identifies resources to precache. This increases the initial download time for the application, but ensures quicker access to the identified resources. Each entry type can be repeated. For example, to precache 10 images, include an <image>element for each image.

  • <image>: Identifies an image resource to precache. Specify a path relative to the Resources directory. Images are base64-encoded into data URI's.
  • <include>: Identifies an Ti.include()'d JavaScript file to precache. Specify a path relative to the Resources directory.
  • <locale>: Identifies a set of locale resources to precache. Specify a language code, for example, "en" for English.
  • <require>: Identifies a CommonJS module included in your local source tree to precache. Specify a module identifier. Not required for Titanium Plus modules.
Example: Cache some resources
<precache>
    <image>images/background.png</image>
    <include>libs/foo.js</include>
    <locale>es</locale>
    <require>modules/foobar.js</require>
</precache>

splash

Controls display of the splash screen.

  • <enabled>: Determines whether the splash screen is displayed. Defaults to true.
  • <inline-css-images>: If true, splash screen images are included in the initial download, which allows the splash screen to be loaded more quickly, at the expense of a somewhat larger initial download.
Example: Enable the splash screen but do no preload it
<splash>
    <enabled>true</enabled>
    <inline-css-images>false</inline-css-images>
</splash>

theme

Currently, only default is supported. Do not change this value.

Windows-specific section

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:

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 capability but it's not listed as a capability in the tiapp.xml:

app.js:

 

Ti.App.setProximityDetection(true);

 

tiapp.xml

 

<windows>
    <manifest>
        <Capabilities>
            <Capability Name="internetClient" />
            <Capability Name="picturesLibrary" />
        </Capabilities>
    </manifest>
</windows>

 

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

The result should be this:

 

...
<Capabilities>
    <Capability Name="internetClient" />
    <uap:Capability Name="picturesLibrary" />
    <DeviceCapability Name="proximity" />
</Capabilities>
...

 

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:

 

<manifest>
    <Capabilities>
        <DeviceCapability Name="location" />
    </Capabilities>
</manifest>

 

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

 

...
<Capabilities>
    <Capability Name="internetClient" />
    <DeviceCapability Name="location"/>
</Capabilities>
...

 

Internet capability

Enabled by default, required for Titanium.Network.*

<ti:app>
  ...
  <windows>
    <manifest>
      <Capabilities>
        <Capability Name="internetClient" />
      </Capabilities>
    </manifest>
  </windows>
  ...
</ti:app>
Location capability

Required for Titanium.Geolocation

<ti:app>
  ...
  <windows>
    ...
    <manifest>
      <Capabilities>
        <DeviceCapability Name="location" />
      </Capabilities>
    </manifest>
    ...
  </windows>
  ...
</ti:app>
Background audio capability

Required for Titanium.Media.AudioPlayer background audio functionality

<ti:app>
  ...
  <windows>
    ...
    <manifest>
      <Extensions>
        <Extension Category="windows.backgroundTasks" Executable="$targetnametoken$.exe" EntryPoint="TitaniumWindows_Media.AudioBackground">
          <BackgroundTasks>
            <Task Type="audio" />
          </BackgroundTasks>
        </Extension>
      </Extensions>
    </manifest>
    ...
  </windows>
  ...
</ti:app>
Audio recorder

Required for Titanium.Media.AudioRecorder functionality

<ti:app>
  ...
  <windows>
    ...
    <Capabilities>
        <Capability Name="musicLibrary" />
        <DeviceCapability Name="microphone" />
        <DeviceCapability Name="webcam" />
    </Capabilities>
    ...
  </windows>
  ...
</ti:app>
Photo gallery

Required for Titanium.Media.openPhotoGallery functionality

<ti:app>
  ...
  <windows>
    ...
    <Capabilities>
        <Capability Name="picturesLibrary" />
    </Capabilities>
    ...
  </windows>
  ...
</ti:app>

 

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

<ti:app>
  ...
  <windows>
    ...
    <manifest target="phone">
      <Capabilities>
        <DeviceCapability Name="location" />
      </Capabilities>
    </manifest>
    <manifest target="store">
      <Capabilities>
        <Capability Name="internetClient" />
      </Capabilities>
    </manifest>
    ...
  </windows>
  ...
</ti:app>

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

Handling differing capabilities between Windows 8.1 and 10

Windows Phone 8.1:

<ti:app>
    ...
    <windows>
        <manifest target="phone" version="8.1">
            <Capabilities>
                <Capability Name="appointments" />
            </Capabilities>
        </manifest>
    </windows>
    ...
</ti:app>

Windows 8.1 Store 

<ti:app>
    ...
    <windows>
        <manifest target="store" version="8.1">
            <Capabilities>
                <Capability Name="musicLibrary" />
            </Capabilities>
        </manifest>
    </windows>
    ...
</ti:app>

Windows 10 is universal so target doesn't matter:

<ti:app>
    ...
    <windows>
        <manifest version="10.0">
            <Capabilities>
                <Capability Name="contacts"/>
            </Capabilities>
        </manifest>
    </windows>
    ...
</ti:app>

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

<ti:app>
    ...
    <windows>
        <manifest>
            <Capabilities>
                <Capability Name="internetClient" />
            </Capabilities>
        </manifest>
    </windows>
    ...
</ti:app>

Windows-specific application properties

Property Name Description
ti.windows.publishername

Must match the Windows publisher ID of your Microsoft Developer account. Used by the Titanium for the Windows SDKs to generate signing certificates and sign your package.

 To retrieve your Windows publisher ID:

 

  1. Log into https://dev.windows.com.
  2. Click Dashboard in the top-right corner.
  3. Click Account settings in the left navigation.

 

The publisher GUID will be under the Account details section as the Windows publisher ID field.

Example:

<property name="ti.windows.publishername" type="string”>CN=11111111-2222-3333-4444-555555555555</property> 

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.

Property Name

Type

Default Value

Description

acs-api-key

string

N/A

Arrow API key. Generated when enabling the project for Cloud services.

acs-base-url string

https://api.cloud.appcelerator.com

Arrow API URL. DO NOT SET OR MODIFY UNLESS INSTRUCTED TO.
acs-grouped-notification-message string N/A Specifies the message to display for grouped notifications, for example, "You have $number$ unread messages." The $number$ variable represents the number of unread messages. This property is also supported in the strings.xml file under the i18n folder for internationalized versions.

acs-push-api-url

string https://api.cloud.appcelerator.com/ Mobile Backend Services dispatcher URL for Android GCM or FCM push notifications. Firebase Cloud Messaging (FCM) is the new version of GCM. DO NOT SET OR MODIFY UNLESS INSTRUCTED TO.
acs-authbase-url string

https://secure-identity.cloud.appcelerator.com

OAuth authentication is no longer supported in the ti.cloud module.

Arrow Authentication URL.
acs-oauth-key string N/A OAuth authentication is no longer supported in the ti.cloud module.

ACS OAuth key. Generated when enabling the project for Cloud services.
acs-oauth-secret string N/A OAuth authentication is no longer supported in the ti.cloud module.

ACS OAuth secret. Generated when enabling the project for Cloud services.

acs-push-type

string

gcm

Deprecated since Release 3.2.0. The ti.cloudpush module now only supports GCM or FCM. Firebase Cloud Messaging (FCM) is the new version of GCM.

Selects the push notification type for Android devices, either gcm or mqtt.

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:

timodule.xml
<android xmlns:android="http://schemas.android.com/apk/res/android">
  <manifest>
    <permission android:name="${tiapp.properties['id']}.permission.MY_NEW_PERMISSION"
		android:protectionLevel="signature" />
  </manifest>
</android>

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:

<permission android:name="com.example.app.permission.MY_NEW_PERMISSION"
		android:protectionLevel="signature" />

Related Links