Titanium.Platform
The top-level Platform module. The Platform module is used to access the device's platform-related functionality.
Extends: Titanium.Module · Since: 0.1
Properties #
apiName#
Type: 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, Button
returns Ti.UI.Button.
BATTERY_STATE_CHARGING#
Type: Number
Constant to indicate that the system is plugged in and currently being charged.
BATTERY_STATE_UNKNOWN#
Type: Number
Constant to indicate that the battery state is not known or monitoring is disabled.
batteryLevel#
Type: Number
Battery level in percent, accessible only when batteryMonitoring is enabled. Measured
in 5% increments on iPhone/iPad.
batteryState#
Type: Number
Indicates the state of the battery. Accessible only when batteryMonitoring is enabled.
bubbleParent#
Type: 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.
displayCaps#
Type: 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#
Type: 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 Titanium.Platform.identifierForVendor instead.
To use a UUID for tracking / advertising purposes,
use Titanium.Platform.identifierForAdvertising instead.
identifierForAdvertising#
Type: String
An alphanumeric string unique to each device, used only for serving advertisements.
Unlike the Titanium.Platform.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#
Type: 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#
Type: 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#
Type: 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#
Type: 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#
Type: 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#
Type: 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#
Type: String
Manufacturer of the device.
Returns the manufacturer of the device, for example, motorola.
Virtual devices return unknown.
model#
Type: 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#
Type: 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 Titanium.Platform.osname
instead.
osname#
Type: String
Short name of the system's Operating System. Returns android for the Android platform,
iphone for the iPhone or iPod Touch, ipad for the iPad, windowsphone for Windows Phone, and windowsstore for Windows Store
platform.
runtime#
Type: String
Short name of the JavaScript runtime in use.
On iOS this is "javascriptcore", on Android either "v8" or "rhino".
uptime#
Type: 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#
Type: String
System name, if set. On iOS, this can be found in Settings > General > About > Name.
versionMajor#
Type: Number
The operating system's major version number.
This returns the same value as the OS_VERSION_MAJOR constant.
versionMinor#
Type: 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#
Type: 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 #
Adds the specified callback as an event listener for the named event.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. | No |
applyProperties #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
props | Dictionary | A dictionary of properties to apply. | No |
canOpenURL #
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>
| Name | Type | Summary | Optional |
|---|---|---|---|
url | String | The URL to check. | No |
Returns: Boolean
cpus #
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: Array<CPU>
fireEvent #
Fires a synthesized event to any registered listeners.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. | Yes |
is24HourTimeFormat #
Returns whether the system settings are configured to show times in 24-hour format.
Returns: Boolean
openURL #
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 Titanium.Platform.canOpenURL method to determine if the system has a registered
application for the given URL before invoking the Titanium.Platform.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);
});
| Name | Type | Summary | Optional |
|---|---|---|---|
url | String | The URL to open. | No |
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. | Yes |
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. | Yes |
Returns: Boolean
removeEventListener #
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);
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to addEventListener. | No |
Events #
battery #
Fired when the battery state changes. This is measured in 5% increments on iPhone/iPad.
| Name | Type | Summary |
|---|---|---|
state | Number | The battery state. |
level | Number | Percentage battery power level. |
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);
});