@maccesar/titools 3.2.0 → 4.0.0

package/skills/ti-guides/references/tiapp-config.md

@@ -0,0 +1,655 @@
+# tiapp.xml and timodule.xml configuration
+
+Reference for Titanium app configuration files. `tiapp.xml` is the main config file for Titanium apps. `timodule.xml` is for custom modules.
+
+## tiapp.xml structure
+
+```xml
+<ti:app xmlns:ti="http://ti.tidev.io">
+  <id>com.titaniumsdk.helloWorld</id>
+  <name>helloWorld</name>
+  <version>1.0.1</version>
+  <icon>appicon.png</icon>
+  <fullscreen>false</fullscreen>
+  <navbar-hidden>false</navbar-hidden>
+  <analytics>false</analytics>
+  <guid>GUID</guid>
+  <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>
+  <android xmlns:android="http://schemas.android.com/apk/res/android">
+    <tool-api-level>10</tool-api-level>
+    <abi>all</abi>
+  </android>
+  <modules/>
+</ti:app>
+```
+
+tiapp.xml properties are encrypted when building for production.
+
+---
+
+## Top-level elements
+
+### Required elements
+
+#### `<guid>`
+
+Required. Unique ID generated by the CLI. Do not modify unless you know why.
+
+#### `<id>`
+
+Required. Application ID.
+
+- Android: package ID following Java package naming standards
+- iOS: must match Bundle ID from Apple Developer Portal
+
+```xml
+<id>com.mycompany.fakeblock</id>
+```
+
+#### `<name>`
+
+Required. Application name shown under the icon on device.
+
+```xml
+<name>Fakeblock</name>
+```
+
+Android warning: if the name starts with a digit, prefix the activity name with an underscore (for example, `_2Foo`).
+
+### Optional elements
+
+#### `<defaultLang>`
+
+Sets the default language for Android i18n `strings.xml`. Android defaults to `en`. If you only use a single non-English i18n file, set this to that language.
+
+```xml
+<defaultLang>de</defaultLang>
+```
+
+#### `<copyright>`
+
+Application copyright.
+
+#### `<description>`
+
+Application description.
+
+```xml
+<description>Tap to rock out with this block.</description>
+```
+
+#### `<fullscreen>`
+
+Start the app in fullscreen (hides the status bar).
+
+```xml
+<fullscreen>false</fullscreen>  <!-- default -->
+```
+
+#### `<icon>`
+
+Icon filename relative to `Resources/` or a platform-specific folder.
+
+```xml
+<icon>appicon.png</icon>
+```
+
+#### `<navbar-hidden>`
+
+Hide the navigation bar.
+
+```xml
+<navbar-hidden>false</navbar-hidden>  <!-- default -->
+```
+
+Android: removes the top action/title bar.
+
+#### `<publisher>`
+
+Application publisher.
+
+```xml
+<publisher>Bluth Company</publisher>
+```
+
+#### `<statusbar-hidden>`
+
+Android only. Hide the status bar.
+
+```xml
+<statusbar-hidden>false</statusbar-hidden>  <!-- default -->
+```
+
+#### `<url>`
+
+Application URL.
+
+```xml
+<url>http://www.bluthcompany.com/fakeblock</url>
+```
+
+#### `<version>`
+
+Application version.
+
+```xml
+<version>3.1.4</version>
+```
+
+iOS: truncated to 3 dot-separated numbers (for example, `2.1.0.1` becomes `2.1.0`).
+
+#### `<sdk-version>`
+
+Titanium SDK to build against.
+
+```xml
+<sdk-version>11.1.0.GA</sdk-version>
+```
+
+#### `<deployment-targets>`
+
+IDE deployment menu options.
+
+```xml
+<deployment-targets>
+    <target device="android">true</target>
+    <target device="ipad">false</target>
+    <target device="iphone">false</target>
+</deployment-targets>
+```
+
+#### `<modules>`
+
+Include Titanium modules.
+
+```xml
+<modules>
+    <module>ti.map</module>
+    <module platform="android">ti.map</module>
+    <module platform="ios">ti.map</module>
+    <module version="2.0.0">ti.alloy</module>
+    <module deploy-type="production">ti.analytics</module>
+</modules>
+```
+
+Attributes:
+- `platform`: `android`, `commonjs`, `iphone`
+- `version`: specific module version
+- `deploy-type`: `development`, `test`, `production` (comma-separated)
+
+#### `<plugins>`
+
+Include plugins (in the `plugins/` folder).
+
+```xml
+<plugins>
+    <plugin version="1.0">ti.alloy</plugin>
+</plugins>
+```
+
+---
+
+## Application properties
+
+Custom properties accessible via `Titanium.App.Properties`. Read-only in production.
+
+```xml
+<property name="name" type="type">value</property>
+```
+
+Types: `string`, `bool`, `int`, `double`
+
+### Special properties
+
+#### `ti.ui.defaultunit`
+
+Default unit for sizes/positions.
+
+```xml
+<property name="ti.ui.defaultunit">system</property>
+```
+
+Values: `system`, `cm`, `dip`/`dp`, `in`, `mm`, `px`
+
+#### `run-on-main-thread`
+
+Since 5.1.0. Run all JavaScript on the main thread instead of a secondary thread. Disabled by default in existing projects, enabled in new projects. Enabled automatically in SDK 7.0.0+.
+
+```xml
+<property name="run-on-main-thread" type="bool">true</property>
+```
+
+#### `allow-custom-keyboards`
+
+Since 6.1.0. Allow or disallow custom iOS 8+ keyboard extensions. Custom keyboards are allowed by default. Set to `false` to disallow them.
+
+```xml
+<property name="allow-custom-keyboards" type="bool">false</property>
+```
+
+---
+
+## Android section
+
+```xml
+<android xmlns:android="http://schemas.android.com/apk/res/android">
+  <abi>all</abi>
+  <activities>
+    <activity url="activity.js"/>
+  </activities>
+  <services>
+    <service url="service.js" type="standard"/>
+  </services>
+  <manifest>
+    <uses-sdk android:minSdkVersion="10" android:targetSdkVersion="14"/>
+    <application>
+        <activity>...</activity>
+        <service>...</service>
+    </application>
+  </manifest>
+</android>
+```
+
+### Elements
+
+#### `<abi>`
+
+Target ABI architecture (V8 runtime only).
+
+```xml
+<abi>all</abi>  <!-- default -->
+```
+
+Values: `all`, `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`
+
+Targeting specific ABIs reduces APK size but also reduces device compatibility.
+
+#### `<activities>`
+
+Custom JavaScript-based Android activities.
+
+```xml
+<activities>
+    <activity url="activity.js">
+        <!-- Android Manifest elements -->
+    </activity>
+</activities>
+```
+
+#### `<services>`
+
+Custom JavaScript-based Android services (background processes).
+
+```xml
+<services>
+    <service url="service.js" type="standard"/>
+</services>
+```
+
+#### `<manifest>`
+
+Ad-hoc AndroidManifest.xml elements.
+
+Set target/minimum SDK:
+```xml
+<android xmlns:android="http://schemas.android.com/apk/res/android">
+    <manifest>
+        <!-- Target Android 10.0, min Android 5.0 -->
+        <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="29"/>
+    </manifest>
+</android>
+```
+
+Screen density support:
+```xml
+<manifest>
+    <supports-screens
+        android:smallScreens="true"
+        android:normalScreens="true"
+        android:largeScreens="true"
+        android:xlargeScreens="true"
+    />
+</manifest>
+```
+
+Do not set `android:anyDensity="false"`.
+
+Enable debugging:
+```xml
+<manifest>
+    <application android:debuggable="true" />
+</manifest>
+```
+
+Install location:
+```xml
+<manifest android:installLocation="preferExternal">
+    <uses-sdk android:minSdkVersion="7" />
+</manifest>
+```
+
+Values: `preferExternal`, `auto`, `internalOnly`
+
+Request large heap:
+```xml
+<manifest>
+    <application android:largeHeap="true"/>
+</manifest>
+```
+
+### Android-specific properties
+
+| Property                               | Type   | Default | Description                                |
+| -------------------------------------- | ------ | ------- | ------------------------------------------ |
+| `ti.android.shake.factor`              | double | 1.3     | Shake event sensitivity                    |
+| `ti.android.shake.quiet.milliseconds`  | int    | 500     | Quiet time before shake event              |
+| `ti.android.shake.active.milliseconds` | int    | 1000    | Active time for shake event                |
+| `ti.android.httpclient.maxbuffersize`  | int    | 524288  | HTTP response buffer size (bytes)          |
+| `ti.android.compilejs`                 | bool   | -       | Enable JS compilation (default: dist only) |
+| `ti.android.debug`                     | bool   | false   | Enable detailed logging                    |
+
+```xml
+<property name="ti.android.fastdev">false</property>
+```
+
+---
+
+## iOS section
+
+```xml
+<ti:app>
+  <ios>
+    <team-id>YOUR_TEAM_ID</team-id>
+    <entitlements>
+      <dict>
+        <key>com.apple.security.application-groups</key>
+        <array>
+          <string>group.com.titaniumsdk.mycoolapp</string>
+        </array>
+      </dict>
+    </entitlements>
+    <extensions>
+      ...
+    </extensions>
+    <plist>
+      <dict>
+        <!-- Info.plist entries -->
+      </dict>
+    </plist>
+    <use-autolayout>true</use-autolayout>
+    <min-ios-ver>9.0</min-ios-ver>
+  </ios>
+</ti:app>
+```
+
+### Elements
+
+#### `<team-id>`
+
+Since 5.0.0. Required for app extensions (share, watch, Siri).
+
+```xml
+<team-id>YOUR_TEAM_ID</team-id>
+```
+
+#### `<entitlements>`
+
+Since 6.1.0. Target entitlements (merged with internal entitlements).
+
+```xml
+<entitlements>
+  <dict>
+    <key>com.apple.security.application-groups</key>
+    <array>
+      <string>group.com.titaniumsdk.mycoolapp</string>
+    </array>
+  </dict>
+</entitlements>
+```
+
+#### `<extensions>`
+
+Since 5.0.0. iOS extensions.
+
+```xml
+<extensions>
+  <extension projectPath="extensions/foo/foo.xcodeproj">
+    <target name="foo WatchApp Extension">
+      <provisioning-profiles>
+        <devices/>
+        <dist-appstore/>
+        <dist-adhoc/>
+      </provisioning-profiles>
+    </target>
+  </extension>
+</extensions>
+```
+
+#### `<min-ios-ver>`
+
+Minimum iOS version.
+
+```xml
+<min-ios-ver>9.0</min-ios-ver>  <!-- default -->
+```
+
+#### `<min-sdk-ver>`
+
+Minimum Xcode version.
+
+```xml
+<min-sdk-ver>9.0</min-sdk-ver>  <!-- default -->
+```
+
+#### `<plist>`
+
+Settings for generated `Info.plist`. Uses key/value pairs.
+
+Orientations:
+```xml
+<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>
+```
+
+Background modes:
+```xml
+<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>
+```
+
+Device capabilities:
+```xml
+<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>
+```
+
+Persistent WiFi:
+```xml
+<key>UIRequiresPersistentWiFi</key><true/>
+```
+
+Status bar style:
+```xml
+<key>UIStatusBarStyle</key><string>UIStatusBarStyleBlackTranslucent</string>
+```
+
+iOS 9 URL schemes:
+```xml
+<key>LSApplicationQueriesSchemes</key>
+<array>
+    <string>fbapi</string>
+    <string>fbauth2</string>
+    <string>twitter</string>
+    <string>whatsapp</string>
+    <string>instagram</string>
+    <string>comgooglemaps</string>
+</array>
+```
+
+#### `<use-app-thinning>`
+
+Since 5.1.0. Enable App Thinning with Asset Catalog.
+
+```xml
+<use-app-thinning>true</use-app-thinning>
+```
+
+Use `Ti.Filesystem.getAsset()` to read images from Asset Catalog.
+
+#### `<use-autolayout>`
+
+Since 5.1.0. Enable iOS auto-layout engine.
+
+```xml
+<use-autolayout>true</use-autolayout>
+```
+
+#### `<log-server-port>`
+
+Since 6.0.0. Custom log server port.
+
+```xml
+<log-server-port>27973</log-server-port>
+```
+
+### Unsupported Info.plist keys
+
+These are auto-generated by Titanium and cannot be overridden:
+- `CFBundleDisplayName`
+- `CFBundleExecutable`
+- `CFBundleIconFile`
+- `CFBundleIconFiles`
+- `CFBundleIdentifier`
+- `CFBundleInfoDictionaryVersion`
+- `CFBundleName`
+- `CFBundlePackageType`
+- `CFBundleSignature`
+- `CFBundleVersion` (pre-4.1.0)
+- `CFBundleShortVersionString` (pre-4.1.0)
+
+---
+
+## Google Play Services
+
+Since 9.0.0. Automatic validation of Google Play Services. Disable if needed:
+
+```xml
+<property name="ti.playservices.validate.on.startup" type="bool">false</property>
+```
+
+---
+
+## timodule.xml (module configuration)
+
+Used in custom Titanium modules. Follows the same structure as `tiapp.xml` but only contains platform-specific config (mainly Android).
+
+Supports token substitution for app-specific values:
+
+```xml
+<!-- 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>
+```
+
+Becomes (for app with ID `com.example.app`):
+
+```xml
+<permission android:name="com.example.app.permission.MY_NEW_PERMISSION"
+android:protectionLevel="signature" />
+```
+
+Access properties:
+- `${tiapp.properties['id']}`: app ID
+- `${tiapp.properties['name']}`: app name
+- `${tiapp.properties['version']}`: app version
+- `${tiapp.properties['publisher']}`: publisher
+
+---
+
+## SDK version precedence
+
+The CLI checks SDK version in this order:
+
+1. `tiapp.xml` `<sdk-version>` tag
+2. `--sdk` CLI option
+3. `app.sdk` config setting (`ti config app.sdk <version>`)
+4. Selected SDK (`ti sdk select`)
+
+---
+
+## References
+
+- Android Manifest docs: http://developer.android.com/guide/topics/manifest/manifest-intro.html
+- iOS Info.plist Key Reference: http://developer.apple.com/library/ios/#documentation/general/Reference/InfoPlistKeyReference/Articles/iPhoneOSKeys.html
+- Java package naming: http://download.oracle.com/javase/tutorial/java/package/namingpkgs.html