# 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>
  <modules/>
</ti:app>

⚠️ Warning

A note about encryption and tiapp.xml: tiapp.xml properties are encrypted when building the app for production.

# 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 (opens new window).

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

Example

<id>com.mycompany.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>

⚠️ Warning

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>
</deployment-targets>

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

Example: Default icon in

<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: development, test 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>

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.

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

Example: Use Titanium SDK 8.0.0 GA

<sdk-version>8.0.0.GA</sdk-version>

# url

The URL of this application.

Example

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

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

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 (opens new window). These properties must be placed inside theroot <ti:app>element.

⚠️ Warning

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>
  • nameis the property name

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

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

  • dipor 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

⚠️ Warning

As of Titanium 8.0.0, tiapp.xml property intent-filter-new-task is no longer supported. If a Titanium app is currently in the background, then an intent will now resume it and fire a "newintent" event. All apps will now simulate "singleTask"-like behavior automatically

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:

tiapp.xml

<property name="intent-filter-new-task" type="bool">true</property>

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.

<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 (opens new window) 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 the 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.

# manifest

Ad-hoc XML from AndroidManifest.xml (opens new window). 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 (opens new window).

# 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 (opens new window).

# 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 (opens new window).

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

# 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 (opens new window)
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.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.

(As of Titanium 8.0.0, this property is no longer supported.)

Example: Disable Fastdev

<property name="ti.android.fastdev">false</property>

# Properties to work around Android bugs 2373 and 5277

⚠️ Warning

As of Titanium 8.0.0, this has been deprecated. The new behavior is a data intent will resume a backgrounded app will be resumed and the fire a "newintent" event. Also, the restart dialog box has been removed.

See TIMOB-4941 (opens new window), TIMOB-1559 (opens new window) and TIMOB-9285 (opens new window) for information about the Titanium workaround to Google issues 2373 (opens new window) and 5277 (opens new window). TIMOB-9285 in particular has a useful explanation (opens new window) 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 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 (opens new window) 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

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.

<android xmlns:android="http://schemas.android.com/apk/res/android">
    <manifest>
        <!-- Target Android 10.0 and set min OS version supported to Android 5.0. -->
        <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="29"/>
    </manifest>
</android>

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

❗️ Warning

Do not set the android:anyDensity attribute to false. Google does not recommend changing the default value (opens new window). 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 (opens new window) 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 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>

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

Example: Enable app-groups for app-extensions

<ti:app>
  <ios>
    <team-id>YOUR_TEAM_ID</team-id>
  <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 "9.0".

Example: Set 9.0 as the minimum iOS version

<ios>
    <!-- Require iOS 9.0 or later -->
    <min-ios-ver>9.0</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 (opens new window) 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

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 (opens new window) to layout the children components of a view. Disabled by default.

❗️ Experimental Feature

This is an experimental feature with known issues:

If you find any issue using this feature, file a bug in JIRA (opens new window).

<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

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

❗️ Warning

Support for Windows 8.1 and Windows Phone SDKs has been deprecated as of SDK 6.3.0.GA and has be removed in SDK 7.0.0.GA.

Add the <manifest> element as a child of the <windows> element to include ad-hoc Windows appx.manifest XML elements (opens new window). 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>

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 (opens new window)

# 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:

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

# Handling differing capabilities between Windows 8.1 and 10

❗️ Warning

Support for Windows 8.1 and Windows Phone SDKs has been deprecated as of SDK 6.3.0.GA and has be removed in SDK 7.0.0.GA.

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 (opens new window).

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:

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

# 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 (opens new window) (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 (opens new window) (FCM) is the new version of GCM.


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

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

<ti:app>
    <property name="ti.playservices.validate.on.startup" type="bool">false</property>
</ti:app>

# 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" />