# Titanium.Platform

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

- Source: https://titaniumsdk.com/docs/sdk/Titanium.Platform
- Titanium SDK version: 13.4.1
- Kind: module
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.1
- Extends: Titanium.Module
- Inheritance: Titanium.Module > Titanium.Proxy

## Example: Battery Event Example

Obtaining battery data when the battery state changes.

``` js
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

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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

### architecture

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

System's processor architecture.

### availableMemory

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

System's unused memory, measured in bytes.

### BATTERY_STATE_CHARGING

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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

### BATTERY_STATE_FULL

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Constant to indicate that the battery is fully charged.

### BATTERY_STATE_UNKNOWN

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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

### BATTERY_STATE_UNPLUGGED

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Constant to indicate that the system is unplugged.

### batteryLevel

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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

### batteryMonitoring

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Default: `false`

Determines whether battery monitoring is enabled.

### batteryState

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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

Accepts: `Titanium.Platform.BATTERY_STATE_CHARGING`, `Titanium.Platform.BATTERY_STATE_FULL`, `Titanium.Platform.BATTERY_STATE_UNKNOWN`, `Titanium.Platform.BATTERY_STATE_UNPLUGGED`

### displayCaps

- Type: Titanium.Platform.DisplayCaps
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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](http://nshipster.com/uuid-udid-unique-identifier/)
documentation.

To use a UUID across different applications of the same vendor,
use [Titanium.Platform.identifierForVendor](https://titaniumsdk.com/docs/sdk/Titanium.Platform.md#identifierForVendor) instead.

To use a UUID for tracking / advertising purposes,
use [Titanium.Platform.identifierForAdvertising](https://titaniumsdk.com/docs/sdk/Titanium.Platform.md#identifierForAdvertising) instead.

### identifierForAdvertising

- Type: String
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 7.0.0

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

Unlike the [Titanium.Platform.identifierForVendor](https://titaniumsdk.com/docs/sdk/Titanium.Platform.md#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
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 7.0.0
- Permission: read-only

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](https://developer.apple.com/reference/uikit/uidevice/1620059-identifierforvendor) for more infos.

### isAdvertisingTrackingEnabled

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 7.0.0
- Permission: read-only

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
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 12.0.0
- Permission: read-only

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.

### locale

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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](http://en.wikipedia.org/wiki/ISO_639-1) and
[ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
sections of wikipedia for reference.

### macaddress

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.0.0
- Permission: read-only

Manufacturer of the device.

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

### model

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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.

Example: Testing for a Virtual Device

Determine whether the application is running on a virtual device.

``` js
if (Ti.Platform.model.indexOf('Simulator') !== -1 || Ti.Platform.model.indexOf('sdk') !== -1 ){
  alert('Accelerometer does not work on a virtual device');
} else {
  // Add Accelerometer event listener
}
```

### name

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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](https://titaniumsdk.com/docs/sdk/Titanium.Platform.md#osname)
instead.

### netmask

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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

### osname

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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.

### ostype

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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

### processorCount

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Number of logical processing cores.

### runtime

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Short name of the JavaScript runtime in use.

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

### totalMemory

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

System's total memory, measured in bytes.

### uptime

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api).

### username

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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

### version

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

The operating system's version string.

### versionMajor

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 9.2.0
- Permission: read-only

The operating system's major version number.

This returns the same value as the [OS_VERSION_MAJOR](https://titaniumsdk.com/docs/sdk/Global.md#OS_VERSION_MAJOR) constant.

### versionMinor

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 9.2.0
- Permission: read-only

The operating system's minor version number.

This returns the same value as the [OS_VERSION_MINOR](https://titaniumsdk.com/docs/sdk/Global.md#OS_VERSION_MINOR) constant.

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

### versionPatch

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 9.2.0
- Permission: read-only

The operating system's patch version number.

This returns the same value as the [OS_VERSION_PATCH](https://titaniumsdk.com/docs/sdk/Global.md#OS_VERSION_PATCH) constant.

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

## Methods

### canOpenURL

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 8.1.0, iPhone 0.8, iPad 0.8

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](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Appendices/tiapp.xml_and_timodule.xml_Reference.html#ios9-security-and-canopenurl).

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](https://developer.android.com/preview/privacy/package-visibility).

```xml
<ti:app xmlns:ti="http://ti.titaniumsdk.com">
    <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:

- `url` (String): The URL to check.

Returns: Boolean

### cpus

- Platforms: Android
- Since: Titanium SDK 8.0.0

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>

### createUUID

- Platforms: Android, iPhone, iPad, macOS

Creates a globally-unique identifier.

Returns: String

### is24HourTimeFormat

- Platforms: Android, iPhone, iPad, macOS

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

Returns: Boolean

### openURL

- Platforms: Android, iPhone, iPad, macOS

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](https://titaniumsdk.com/docs/sdk/Titanium.Platform.md#canOpenURL) method to determine if the system has a registered
application for the given URL before invoking the [Titanium.Platform.openURL](https://titaniumsdk.com/docs/sdk/Titanium.Platform.md#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:
``` js
Ti.Platform.openURL('myapp://', {
  'UIApplicationOpenURLOptionUniversalLinksOnly': true
}, function(e) {
  Ti.API.info('URL open successfully? ' + e.success);
});
```

Parameters:

- `url` (String): The URL to open.
- `options` (OpenURLOptions, optional): 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](https://developer.apple.com/documentation/uikit/uiapplicationopenurloptionskey?language=objc).
- `callback` (Callback, optional): The optional callback that is called once the URL is opened (iOS 10+). Also supported on Android as of Titanium 9.1.0.

Returns: Boolean

## Events

### battery

- Platforms: Android, iPhone, iPad, macOS

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

Event properties:

- `state` (Number): The battery state.
- `level` (Number): Percentage battery power level.

## Inherited members

7 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.