Titanium SDK

# Titanium.Platform

The top-level Platform module. The Platform module is used to access the device's platform-related functionality.

Availability
0.8
0.8
9.2.0
Extends
Titanium.Module

# Examples

# Battery Event Example

Obtaining battery data when the battery state changes.

Titanium.Platform.addEventListener('battery', function(e){
  Ti.API.info('The battery state has changed to ' + e.state);
  Ti.API.info('The battery level is ' + e.level);
  Ti.API.info('The battery event source is ' + e.source);
  Ti.API.info('The battery event name ' + e.type);
});

# Properties

# address READONLY

Availability
0.8
0.8
9.2.0
address :String

System's WIFI IP address. No other network types are supported.

# apiName READONLY

Availability
3.2.0
3.2.0
9.2.0
apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

# architecture READONLY

Availability
0.8
0.8
9.2.0
architecture :String

System's processor architecture.

# availableMemory READONLY

Availability
0.8
0.8
9.2.0
availableMemory :Number

System's unused memory, measured in bytes.

# batteryLevel READONLY

Availability
0.8
0.8
9.2.0
batteryLevel :Number

Battery level in percent, accessible only when batteryMonitoring is enabled. Measured in 5% increments on iPhone/iPad.

# batteryMonitoring

Availability
0.8
0.8
9.2.0
batteryMonitoring :Boolean

Determines whether battery monitoring is enabled.

Default: false

# batteryState READONLY

Availability
0.8
0.8
9.2.0
batteryState :Number

Indicates the state of the battery. Accessible only when batteryMonitoring is enabled.

This API can be assigned the following constants:

# bubbleParent

Availability
3.0.0
3.0.0
9.2.0
bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

# displayCaps READONLY

Availability
0.8
0.8
9.2.0
displayCaps :Titanium.Platform.DisplayCaps

Returns the DisplayCaps object.

Note that the displayCaps property begins with a lowercase letter, which differentiates it from the DisplayCaps object that it returns.

# id READONLY

Availability
0.8
0.8
9.2.0
id :String

Applications's globally-unique ID (UUID).

On Android, this may be the UDID (unique device ID). For iOS, this is a unique identifier for this install of the application.

Previously on iOS this may have been a UDID, but access to this has been restricted by Apple. For more information, see UUID Article on NSHipster documentation.

To use a UUID across different applications of the same vendor, use identifierForVendor instead.

To use a UUID for tracking / advertising purposes, use identifierForAdvertising instead.

# identifierForAdvertising

Availability
7.0.0
9.2.0
identifierForAdvertising :String

An alphanumeric string unique to each device, used only for serving advertisements.

Unlike the identifierForVendor property, the same value is returned to all vendors. This identifier may change, for example, if the user erases the device, so you should not cache it.

In iOS 10.0 and later, the value of this property is all zeroes when the user has limited ad tracking.

If the value is null, wait and get the value again later. This happens, for example, after the device has been restarted but before the user has unlocked the device.

# identifierForVendor READONLY

Availability
7.0.0
9.2.0
identifierForVendor :String

An alphanumeric string that uniquely identifies a device to the app's vendor.

The value of this property is the same for apps that come from the same vendor running on the same device. A different value is returned for apps on the same device that come from different vendors, and for apps on different devices regardless of vendor. See the Apple docs for more infos.

# isAdvertisingTrackingEnabled READONLY

Availability
7.0.0
9.2.0
isAdvertisingTrackingEnabled :Boolean

A Boolean value that indicates whether the user has limited ad tracking.

Check the value of this property before performing any advertising tracking. If the value is false, use the advertising identifier only for the following purposes: frequency capping, attribution, conversion events, estimating the number of unique users, advertising fraud detection, and debugging.

# isTranslatedBinaryOnAppleSilicon READONLY

Availability
12.0.0
12.0.0
isTranslatedBinaryOnAppleSilicon :Boolean

A Boolean value that indicates whether the current app is running as a translated binary using Rosetta on an Apple Silicon device.

Use this utility property to guard API's that may not be available on a non-iOS device, e.g. motion activity or some authorization components.

# lifecycleContainer

Availability
3.6.0
lifecycleContainer :Titanium.UI.Window | Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.

# locale READONLY

Availability
0.8
0.8
9.2.0
locale :String

System's default language.

Locale, as a combination of ISO 2-letter language and country codes. For example, en-US or en-GB. See the ISO 639-1 and ISO 3166-1 alpha-2 sections of wikipedia for reference.

# macaddress READONLY

Availability
0.8
0.8
9.2.0
macaddress :String

System's network interface mac address, or app UUID.

On iOS, this value is the app's UUID. Apple does not allow access to any hardware identifier information as it can be used for unique device identification, which they have prohibited.

# manufacturer READONLY

Availability
3.0.0
3.0.0
9.2.0
manufacturer :String

Manufacturer of the device.

Returns the manufacturer of the device, for example, motorola. Virtual devices return unknown.

# model READONLY

Availability
0.8
0.8
9.2.0
model :String

Model of the device.

An identifier of the hardware model of the device. For example, HTC Sensation Z710e.

Virtual devices will also return a value. For example, sdk for the standard Android SDK and google_sdk for the enhanced Android Google APIs SDK running in an emulator, and Simulator for iOS running in a simulator.

# name READONLY

Availability
0.8
0.8
9.2.0
name :String

Name of the platform. Returns android for the Android platform, iPhone OS for the iOS platform (iPhone, iPad, or iPod Touch), and windows for the Windows platform.

This property returns iOS for for the iOS platform (iPhone & iPod Touch). For the iPad, it returns iOS for iOS < 13 and iPadOS for iPadOS > 13 as part of the iPadOS rebranding for the iPad. If you need one identifier for both iOS and iPadOS, use osname instead.

# netmask READONLY

Availability
0.8
0.8
9.2.0
netmask :String

System's WIFI network mask. No other network types are supported.

# osname READONLY

Availability
0.8
0.8
9.2.0
osname :String

Short name of the system's Operating System. Returns android for the Android platfrom, iphone for the iPhone or iPod Touch, ipad for the iPad, windowsphone for Windows Phone, and windowsstore for Windows Store platform.

# ostype READONLY

Availability
0.8
0.8
9.2.0
ostype :String

Operating System architecture. On Android, this is 32bit.

# processorCount READONLY

Availability
0.8
0.8
9.2.0
processorCount :Number

Number of logical processing cores.

# runtime READONLY

Availability
0.8
0.8
9.2.0
runtime :String

Short name of the JavaScript runtime in use.

On iOS this is "javascriptcore", on Android either "v8" or "rhino".

# totalMemory READONLY

Availability
0.8
0.8
9.2.0
totalMemory :Number

System's total memory, measured in bytes.

# uptime READONLY

Availability
0.8
0.8
9.2.0
uptime :Number

System uptime since last boot in seconds.

Important: When developing for the Apple ecosystem, using this API requires the NSPrivacyAccessedAPICategorySystemBootTime property set in the privacy manifest that was introduced in iOS 17. You can learn more about it here.

# username READONLY

Availability
0.8
0.8
9.2.0
username :String

System name, if set. On iOS, this can be found in Settings > General > About > Name.

# version READONLY

Availability
0.8
0.8
9.2.0
version :String

The operating system's version string.

# versionMajor READONLY

Availability
9.2.0
9.2.0
9.2.0
versionMajor :Number

The operating system's major version number.

This returns the same value as the OS_VERSION_MAJOR constant.

# versionMinor READONLY

Availability
9.2.0
9.2.0
9.2.0
versionMinor :Number

The operating system's minor version number.

This returns the same value as the OS_VERSION_MINOR constant.

Will return zero if the OS does not have a minor version.

# versionPatch READONLY

Availability
9.2.0
9.2.0
9.2.0
versionPatch :Number

The operating system's patch version number.

This returns the same value as the OS_VERSION_PATCH constant.

Will return zero if the OS does not have a patch version.

# Methods

# addEventListener

Availability
0.8
0.8
9.2.0
addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to invoke when the event is fired.

Returns

Type
void

# applyProperties

Availability
3.0.0
3.0.0
9.2.0
applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# canOpenURL

Availability
8.1.0
0.8
9.2.0
canOpenURL(url) → Boolean

Returns whether the system is configured with a default application to handle the URL's protocol/scheme.

As of iOS 9, this method may return false if you have not added the URL schemes you query to the "tiapp.xml" file. You can do this by adding a <key>LSApplicationQueriesSchemes</key> plist section as shown here.

As of Android 11, this method may return false if you have not added the URL schemes to a <queries/> manifest section in the "tiapp.xml" file. Google documents examples how to do this here.

<ti:app xmlns:ti="http://ti.tidev.io">
    <android>
        <manifest xmlns:android="http://schemas.android.com/apk/res/android">
            <queries>
                <!-- Allows "http://" and "https://" web URLs. -->
                <intent>
                    <action android:name="android.intent.action.VIEW"/>
                    <data android:scheme="https"/>
                </intent>
                <!-- Allows "mailto:" URLs to an e-mail app. -->
                <intent>
                    <action android:name="android.intent.action.VIEW"/>
                    <data android:scheme="mailto"/>
                </intent>
                <!-- Allows file URLs to local image files. -->
                <intent>
                    <action android:name="android.intent.action.VIEW"/>
                    <data android:mimeType="image/*"/>
                </intent>
            </queries>
        </manifest>
    </android>
</ti:app>

Parameters

Name Type Description
url String

The url to check.

Returns

Type
Boolean

# cpus

Availability
8.0.0
cpus() → Array<CPU>

Returns an array of basic cpu information for all logical processors

This is intended to provide an implementation similar to Node's os.cpus().

Returns

Type
Array<CPU>

# createUUID

Availability
0.8
0.8
9.2.0
createUUID() → String

Creates a globally-unique identifier.

Returns

Type
String

# fireEvent

Availability
0.8
0.8
9.2.0
fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name Type Description
name String

Name of the event.

event Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type
void

# is24HourTimeFormat

Availability
0.8
0.8
9.2.0
is24HourTimeFormat() → Boolean

Returns whether the system settings are configured to show times in 24-hour format.

Returns

Type
Boolean

# openURL

Availability
0.8
0.8
9.2.0
openURL(url[, options[, callback]]) → Boolean

Opens this URL using the system's default application for its protocol/scheme.

Here are some example URL strings this can be set to.

  • 'https://www.titaniumsdk.com' (Opens in web browser.)
  • 'mailto:user@domain.com' (Opens a new draft in e-mail app.)
  • 'mailto:user@domain.com?cc=johndoe@domain.com,janedoe@domain.com&subject=My%20Subject&body=The%20body.'
  • 'tel:123-456-7890' (Opens phone app if applicable.)
  • 'geo:37.774,-122.431?z=12' (Opens map on Android.)
  • 'maps:?address=London,UK' (Opens map on iOS.)

You can use the canOpenURL method to determine if the system has a registered application for the given URL before invoking the openURL method.

iOS Note: For iOS 10 and later, this method is performed asynchronously and will call the function passed as an (optional) third parameter instead of returning a boolean synchronously.

Example:

Ti.Platform.openURL('myapp://', {
  'UIApplicationOpenURLOptionUniversalLinksOnly': true
}, function(e) {
  Ti.API.info('URL open successfully? ' + e.success);
});

Parameters

Name Type Description
url String

The url to open.

options OpenURLOptions

The optional options to pass to the URL handling (iOS 10+). Pass a dictionary with one or more of the following string-keys: * UIApplicationOpenURLOptionsSourceApplicationKey (String value) * UIApplicationOpenURLOptionsAnnotationKey (Array value) * UIApplicationOpenURLOptionsOpenInPlaceKey (Boolean value) * UIApplicationOpenURLOptionUniversalLinksOnly (Boolean value) Read more about the available keys in the Apple documentation.

callback Callback

The optional callback that is called once the URL is opened (iOS 10+). Also supported on Android as of Titanium 9.1.0.

Returns

Type
Boolean

# removeEventListener

Availability
0.8
0.8
9.2.0
removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

Returns

Type
void

# Events

# battery

Availability
0.8
0.8
9.2.0

Fired when the battery state changes. This is measured in 5% increments on iPhone/iPad.

Properties

Name Type Description
state Number

The battery state.

level Number

Percentage battery power level.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

# Constants

# BATTERY_STATE_CHARGING

Availability
0.8
0.8
9.2.0
BATTERY_STATE_CHARGING :Number

Constant to indicate that the system is plugged in and currently being charged.

# BATTERY_STATE_FULL

Availability
0.8
0.8
9.2.0
BATTERY_STATE_FULL :Number

Constant to indicate that the battery is fully charged.

# BATTERY_STATE_UNKNOWN

Availability
0.8
0.8
9.2.0
BATTERY_STATE_UNKNOWN :Number

Constant to indicate that the battery state is not known or monitoring is disabled.

# BATTERY_STATE_UNPLUGGED

Availability
0.8
0.8
9.2.0
BATTERY_STATE_UNPLUGGED :Number

Constant to indicate that the system is unplugged.

Contents