Version12.8.0

You are reading 12.8.0. See this page in 13.4.1.

Titanium.App.Properties

moduleAndroidiPhoneiPadmacOSsince 0.5

Extended by Titanium.App.iOS.UserDefaults

The App Properties module is used for storing application-related data in property/value pairs that persist beyond application sessions and device power cycles.

App Properties in the tiapp.xml file

App properties defined in the tiapp.xml file may be accessed using these APIs. An app property is defined inside the root-level <ti:app> element with the <property> element. Use the name attribute to define your property name and place the value inline with the <property> element. For example, to define an app property called foo with the value 42:

<?xml version="1.0" encoding="UTF-8"?>
<ti:app xmlns:ti="http://ti.titaniumsdk.com">
    <property name="foo" type="string">42</property>
</ti:app>

Then, you can retrieve the property during runtime with the following API call:

const foo = Ti.App.Properties.getString('foo');

Any application properties defined in the tiapp.xml file are stored in the device's secure storage, making them read-only. Additionally, external access to these properties is now restricted. Other iOS applications cannot access these properties and native Android modules must use the Titanium module API TiApplication.getAppProperties() method to access these properties.

If you need to change the values during runtime, initially create the property with these APIs rather than defining them in the tiapp.xml file.

Important: Using this API in the Apple ecosystem requires the NSPrivacyAccessedAPICategoryUserDefaults property set in the privacy manifest that was introduced in iOS 17. You can learn more about it here.

Examples

Store a property

Store a string property.

Ti.App.Properties.setString('givenName', 'Paul');
Ti.API.info('The value of the givenName property is: ' + Ti.App.Properties.getString('givenName'));

Enumerate over saved properties

Output all saved properties to the console.

var props = Ti.App.Properties.listProperties();

for (var i = 0, ilen = props.length; i < ilen; i++){
    var value = Ti.App.Properties.getString(props[i]);
    Ti.API.info(props[i] + ' = ' + value);
}

Properties 3

apiName

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

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

Default: true

lifecycleContainer

Titanium.UI.Window | Titanium.UI.TabGroupAndroidsince 3.6.0

Inherited from Titanium.Proxy

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

Methods 20

addEventListener

Inherited from Titanium.Proxy

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

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

applyProperties

since 3.0.0

Inherited from Titanium.Proxy

Applies the properties to the proxy.

Parameters
Parameters	Type	Description
props	Dictionary	A dictionary of properties to apply.

fireEvent

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

Parameters
Parameters	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.

getBool

Returns the value of a property as a boolean data type.

Parameters
Parameters	Type	Description
property	String	Name of property.
default?	Boolean	Default value to return if property does not exist.

Returns Boolean

getDouble

Returns the value of a property as a double (double-precision, floating point) data type.

This method must only be used to retrieve properties created with setDouble.

Parameters
Parameters	Type	Description
property	String	Name of property.
default?	Number	Default value to return if property does not exist.

Returns Number

getInt

Returns the value of a property as an integer data type.

This method must only be used to retrieve properties created with setInt.

Use getDouble and setDouble to store values outside the integer data type range of -2,147,483,648 to 2,147,483,647.

Parameters
Parameters	Type	Description
property	String	Name of property.
default?	Number	Default value to return if property does not exist.

Returns Number

getList

Returns the value of a property as an array data type.

Parameters
Parameters	Type	Description
property	String	Name of property.
default?	Array<Object>	Default value to return if property does not exist.

Returns Array<Object>

getObject

Returns the value of a property as an object.

Parameters
Parameters	Type	Description
property	String	Name of property.
default?	Object	Default value to return if property does not exist.

Returns Object

getString

Returns the value of a property as a string data type.

Parameters
Parameters	Type	Description
property	String	Name of property.
default?	String	Default value to return if property does not exist.

Returns String

hasProperty

Indicates whether a property exists.

Parameters
Parameters	Type	Description
property	String	Name of property.

Returns Boolean

listProperties

Returns an array of property names.

Returns Array<Object>

removeAllProperties

since 6.0.0

Removes all properties that have been set by the user on runtime, or does nothing otherwise.

removeEventListener

Inherited from Titanium.Proxy

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

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

removeProperty

Removes a property if it exists, or does nothing otherwise.

Parameters
Parameters	Type	Description
property	String	Name of property.

setBool

Sets the value of a property as a boolean data type. The property will be created if it does not exist.

Parameters
Parameters	Type	Description
property	String	Name of property.
value	Boolean	Property value.

setDouble

Sets the value of a property as a double (double-precision, floating point) data type. The property will be created if it does not exist.

Parameters
Parameters	Type	Description
property	String	Name of property.
value	Number	Property value.

setInt

Sets the value of a property as an integer data type. The property will be created if it does not exist.

Use getDouble and setDouble to store values outside the integer data type range of -2,147,483,648 to 2,147,483,647.

Parameters
Parameters	Type	Description
property	String	Name of property.
value	Number	Property value, within the range `-2,147,483,648` to `2,147,483,647`.

setList

Sets the value of a property as an array data type. The property will be created if it does not exist.

Parameters
Parameters	Type	Description
property	String	Name of property.
value	Array<Object>	Property value.

setObject

Sets the value of a property as an object data type. The property will be created if it does not exist.

Parameters
Parameters	Type	Description
property	String	Name of property.
value	Object	Property value.

setString

Sets the value of a property as a string data type. The property will be created if it does not exist.

Parameters
Parameters	Type	Description
property	String	Name of property.
value	String	Property value.

Events 1

change

iPhoneiPadmacOSsince 3.0.0

Fired when a property is changed.

On iOS, the event is fired when the user re-enters the application after making a change using the Settings application.

The event is also fired when the application changes a property directly using one of the Ti.App.iOS.UserDefaults or Ti.App.Properties methods.