@maccesar/titools 2.0.0

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

@@ -0,0 +1,609 @@
+# tiapp.xml and timodule.xml Configuration
+
+Complete 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>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**: tiapp.xml properties are encrypted when building for production.
+
+---
+
+## Top-Level Elements
+
+### Required Elements
+
+#### `<guid>`
+**Required.** Unique ID generated by CLI. Do not modify unless you know what you're doing.
+
+#### `<id>`
+**Required.** Application ID.
+
+- **Android**: Package ID following [Java Package Naming Standards](http://download.oracle.com/javase/tutorial/java/package/namingpkgs.html)
+- **iOS**: Must match Bundle ID from Apple Developer Portal
+
+```xml
+<id>com.mycompany.fakeblock</id>
+```
+
+#### `<name>`
+**Required.** Application name shown under icon on device.
+
+```xml
+<name>Fakeblock</name>
+```
+
+**Android warning**: If name starts with a digit, prefix activity name with underscore (e.g., `_2Foo`).
+
+### Optional Elements
+
+#### `<copyright>`
+Application copyright.
+
+#### `<description>`
+Application description.
+
+```xml
+<description>Tap to rock out with this block.</description>
+```
+
+#### `<fullscreen>`
+Start app in fullscreen (hides status bar).
+
+```xml
+<fullscreen>false</fullscreen>  <!-- default -->
+```
+
+#### `<icon>`
+Icon filename relative to `Resources/` or platform-specific folder.
+
+```xml
+<icon>appicon.png</icon>
+```
+
+#### `<navbar-hidden>`
+Hide navigation bar.
+
+```xml
+<navbar-hidden>false</navbar-hidden>  <!-- default -->
+```
+
+**Android**: Removes top action/title bar.
+
+#### `<publisher>`
+Application publisher.
+
+```xml
+<publisher>Bluth Company</publisher>
+```
+
+#### `<statusbar-hidden>`
+**Android only.** Hide 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 (e.g., `2.1.0.1` → `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 `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`
+
+#### `appc-sourcecode-encryption-policy`
+Encryption policy for app assets.
+
+```xml
+<property name="appc-sourcecode-encryption-policy">remote</property>
+```
+
+**Values:**
+- `embed`: Key embedded in binary (padded/obfuscated)
+- `remote`: Key stored remotely (requires internet, default)
+
+#### `appc-security-jailbreak-detect`
+Prevent running on jailbroken/rooted devices.
+
+```xml
+<property name="appc-security-jailbreak-detect">true</property>
+```
+
+**Requires**: `appc-sourcecode-encryption-policy` set to `remote`
+
+#### `appc-security-debugger-detect`
+Prevent debugger connections.
+
+```xml
+<property name="appc-security-debugger-detect">true</property>
+```
+
+**Requires**: `appc-sourcecode-encryption-policy` set to `remote`
+
+---
+
+## 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 ABI reduces APK size but 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](http://developer.android.com/guide/topics/manifest/manifest-intro.html) 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>
+```
+
+**WARNING**: 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>
+  </array>
+</dict>
+</plist>
+```
+
+**Device capabilities:**
+```xml
+<plist>
+<dict>
+  <key>UIRequiredDeviceCapabilities</key>
+  <array>
+    <string>telephony</string>
+    <string>wifi</string>
+    <string>gps</string>
+    <string>accelerometer</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>
+```
+
+**NOTE**: 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 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. SDK select version (`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)