---
description: >-
  Critical moments comes with many properties and functions built in, which you
  can use for your conditional targeting
---

# Built-in Properties

Topics for built in properties include:

* Device information: model name, manufacturer, OS version, etc
* Screen information: size, scale and orientation
* User locale infomation: language, country, currency
* App information: app ID, version number, etc
* Battery state: charging, percent remaining, etc
* Audio information: is the user on a call? Listening to music? Do they have headphones connected?
* Network connectivity: has connection, connection type, etc
* Permissions the user has granted (camera roll, contacts, microphone, etc)
* And more...

<details>

<summary>Free Plan Property List</summary>

The following properties are included in our free plan. The remaining properties require a Pro plan.

```
"platform",
"app_id",
"app_version",
"os_version",
"cm_version",
"device_battery_state",
"device_battery_level",
"device_model",
"device_model_class",
"device_orientation",
"device_manufacturer",
"app_install_date",
"has_active_network",
"screen_brightness",
"user_interface_idiom",
"interface_orientation",
"dark_mode",
"session_start_time",
"app_start_time",
"foreground",
"app_state",
"timezone_gmt_offset",
"locale_country_code",
"locale_language_code",
"locale_language_direction",
"screen_height_points",
"device_model_version",
"screen_width_pixels",
"screen_height_pixels",
"screen_width_points",
"screen_scale",
```

</details>

<table data-full-width="true"><thead><tr><th width="177">Name</th><th width="80">Type</th><th width="129">Example Values</th><th>Details</th></tr></thead><tbody><tr><td>platform</td><td>string</td><td>"iOS", "iPadOS"</td><td><p>The platform this is running on.<br></p><p>Note: for consistency we return "iPadOS" on all iPads, even OS versions before Apple started using the marketing name "iPadOS".<br></p><p>Note: iPad apps running on Mac  return "iPadOS", not MacOS.</p></td></tr><tr><td>user_interface_idiom</td><td>string</td><td>"phone", "tablet", "tv", "car", "computer", "unknown"</td><td><p>The type of device. Always one of the listed example values.</p><p></p><p>Note: iPad apps running on Mac  return "tablet", not "computer".</p></td></tr><tr><td>os_version</td><td>version string</td><td>"16.4.1"</td><td><p>The OS version number as a string.</p><p></p><p>Operators<a href="../syntax-and-operators#version-number-operators"> are available</a> to compare version strings.</p><p></p><p>Note: iPad apps run on Mac will return the iPadOS simulator version they are running on, not the MacOS version of the host OS.</p></td></tr><tr><td>cm_version</td><td>version string</td><td>"1.2.3"</td><td><p>The version number of the CriticalMoments library on this client.</p><p></p><p>Operators<a href="../syntax-and-operators#version-number-operators"> are available</a> to compare version strings.</p></td></tr><tr><td>device_manufacturer</td><td>string</td><td>Apple</td><td>The device manufacturer</td></tr><tr><td>device_model_class</td><td>string</td><td>"iPhone", "iPad" "iPod"</td><td>The manufacturer's description of the device type/class. See <code>user_interface_idiom</code> for a more general description of device type.</td></tr><tr><td>device_model</td><td>string</td><td>"iPhone13,3", "simulator", "iPad13,10"</td><td><p>The manufacturer's description string of this device. </p><p></p><p>List of Apple device models <a href="https://everyi.com/by-identifier/ipod-iphone-ipad-specs-by-model-identifier.html">here</a>. </p></td></tr><tr><td>device_model_version</td><td>nullable version string</td><td>"13.3", "14.2", nil</td><td><p>The floating point portion of device_model as a string. For example, for device_model "iPhone13,3" this field holds "13.3"<br><br>Operators<a href="../syntax-and-operators#version-number-operators"> are available</a> to compare version strings.<br><br>Useful to find sets of devices, for example, to find iPhones newer than the iPhone 12: "device_model_class == "iPhone" &#x26;&#x26; versionNumberComponent(device_model_version, 0) > 13". Yes, the "iPhone 12" has 13 in it’s device_model string… ask Apple not me.<br></p><p>Usually used in conjunction with device_model_class as value comparisons typically only makes sense within a class.</p><p></p><p>Nil on simulators, but populated on real hardware.</p></td></tr><tr><td>dark_mode</td><td>bool</td><td>true, false</td><td>True if the device is set to use the system’s "dark mode" style.</td></tr><tr><td>interface_orientation</td><td>string</td><td>"landscape", "portrait"</td><td><p>The orientation the main screen’s user interface is rendered in.   </p><p></p><p>This may not match the physical orientation if the app only supports some orientations, or the user has rotation lock on.  </p><p></p><p>For the orientation of the physical device regardless of interface rendering, see device_orientation.</p></td></tr><tr><td>device_orientation</td><td>string</td><td>"landscape", "portrait", "face_up", "face_down", "unknown"</td><td><p>The device’s physical orientation, regardless of the orientation the UI is rendered.</p><p></p><p>  Returns face up/down if the device is nearly flat, such as sitting on a table. </p><p></p><p>Returns "unknown" on simulator or devices without accelerometers (computers). </p><p></p><p> For the orientation of the user interface rendering, see interface_orientation.</p></td></tr><tr><td>screen_width_points &#x26; screen_height_points</td><td>integer</td><td>853</td><td><p>The device screen size in "points" - <a href="https://blog.fluidui.com/designing-for-mobile-101-pixels-points-and-resolutions/">https://blog.fluidui.com/designing-for-mobile-101-pixels-points-and-resolutions/</a><br></p><p>The height is always the greater of the two; these are rotation independent. For current orientation, see interface_orientation and device_orientation.</p></td></tr><tr><td>screen_width_pixels &#x26; screen_height_pixels</td><td>integer</td><td>2556</td><td><p>The device screen size in pixels. </p><p></p><p>The height is always the greater of the two; these are rotation independent. For current orientation, see interface_orientation and device_orientation.</p></td></tr><tr><td>screen_scale</td><td>float</td><td>1.0, 2.0, 3.0</td><td><a href="https://developer.apple.com/documentation/uikit/uiscreen/1617836-scale">https://developer.apple.com/documentation/uikit/uiscreen/1617836-scale</a></td></tr><tr><td>screen_brightness</td><td>float</td><td>0.1, 0.9</td><td>The current brightness of the user's screen. Ranges from 0.0 to 1.0 inclusive.</td></tr><tr><td>screen_captured</td><td>bool</td><td>true, false</td><td>True if the user's screen is currently being captured (Airplay mirroring, screen recording, etc).</td></tr><tr><td>locale_language_code</td><td>string</td><td>"en", "es"</td><td>The language from the user-preferred locale</td></tr><tr><td>locale_country_code</td><td>string</td><td>"CA", "US"</td><td>The country from the user-preferred locale</td></tr><tr><td>locale_currency_code</td><td>string</td><td>"CAD", "USD", "EUR", "JPY"</td><td>The currency code from the user-preferred locale.</td></tr><tr><td>locale_language_direction</td><td>string</td><td>"RTL", "LTR"</td><td>Is the device's language right-to-left or left-to-right.</td></tr><tr><td>app_id</td><td>string</td><td>"io.criticalmoments.sampleapp"</td><td><p>The app’s ID. </p><p></p><p>On Apple devices this is the bundle identifier.</p></td></tr><tr><td>app_version</td><td>version string</td><td>"1.2.3.4"</td><td><p>The app version number as a string, such as "1.2.2".   </p><p></p><p>Operators<a href="../syntax-and-operators#version-number-operators"> are available</a> to compare version strings.</p></td></tr><tr><td>app_install_date</td><td>timestamp</td><td>See <a href="conditional-guides/working-with-dates">Working with Dates</a>.</td><td><p>The timestamp this app was installed by the user. </p><p></p><p>If deleted and reinstalled, this will reflect the latest install.</p></td></tr><tr><td>app_start_time</td><td>timestamp</td><td>See <a href="conditional-guides/working-with-dates">Working with Dates</a>.</td><td>The timestamp the app was launched. This is set to when the app started up, and does not get reset to a newer time if the app cycles into the background, then back to forground. If the app is terminated and restarted, it will be set to the latest app start time.</td></tr><tr><td>session_start_time</td><td>timestamp</td><td>See <a href="conditional-guides/working-with-dates">Working with Dates</a>.</td><td>The time the current user session started. A session start both when the app is initially launced, and if the app enters the foreground after 10 mintues or more in the background.  </td></tr><tr><td>is_debug_build</td><td>bool</td><td>true, false</td><td>True if this app was built as a debug build</td></tr><tr><td>device_battery_level</td><td>version string</td><td>0.88</td><td><p>Battery level ranges from 0.0 (fully discharged) to 1.0 (100% charged).<br></p><p>Returns 1.0 on devices that don’t have batteries (simulators, wired computers).</p></td></tr><tr><td>device_battery_state</td><td>string</td><td>"charging", "full", "unplugged", "unknown"</td><td><p>The battery state. Always one of the example values.</p><p></p><p>"full" indicates full and connected to power. To check if it's plugged in, you should check that it's "charging" or "full".<br></p><p>May return unknown on devices that don’t have batteries (simulators, wired computers)</p></td></tr><tr><td>device_low_power_mode</td><td>bool</td><td>true, false</td><td>Returns true if the user has low power mode enabled (typically enabled to save battery).   If this system doesn’t have a low power mode, false is returned.</td></tr><tr><td>network_connection_type</td><td>string</td><td>"wifi", "cellular", "wired", "unkown"</td><td><p>Indicates the type of network connection the device currently uses. </p><p></p><p>Does not imply an working internet connection (see has_active_network).   Device could be connected to an AP that isn't connected to the internet.</p><p></p><p>"unknown" may mean no network connection, but also may be returned when there is an active connection but the type is not known. Check has_active_network to determine if there’s a working internet connection.</p></td></tr><tr><td>has_active_network</td><td>bool</td><td>true, false</td><td>True if the device has an working internet connection</td></tr><tr><td>low_data_mode</td><td>nullable bool</td><td>true, false, nil</td><td><p>Indicates if the user has low data mode enabled, indicating they want to save data.<br></p><p>This value may be nil on devices that do not have this mode (for example, iOS 12 and earlier). If you only want to check for truthiness you can simply check (<code>low_data_mode ?? false)</code> using the nil coalesing operator <code>??</code>.</p><p></p><p><a href="https://support.apple.com/en-us/HT210596">https://support.apple.com/en-us/HT210596</a></p></td></tr><tr><td>expensive_network</td><td>bool</td><td>true, false</td><td><p>True if the network is considered to be expensive by the operating system, such as a cellular network, or wifi connection to a cellular hotspot. False if the OS doesn't have a concept of expensive networks or the network is "cheap".</p><p></p><p><a href="https://developer.apple.com/documentation/network/2976891-nw_path_is_expensive?language=objc">https://developer.apple.com/documentation/network/2976891-nw_path_is_expensive</a></p></td></tr><tr><td>has_wifi_connection</td><td>bool</td><td>true, false</td><td><p>Indicates if the device is connected to a wifi network.<br></p><p><strong>IMPORTANT</strong>: this does not indicate that wifi is the primary network (it may be using cellular — see network_connection_type), or that the wifi connection has an internet connection (see has_active_network). This only indicated that the device is connected to a wifi access point.</p></td></tr><tr><td>has_cell_connection</td><td>bool</td><td>true, false</td><td><p>True if the device is connected to a cellular network.<br></p><p><strong>IMPORTANT</strong>: this does not indicate that cellular is the primary network (it may be using wifi — see network_connection_type), or that the cellular network has an internet connection (see has_active_network). Only that the device is connected to a cellular network.</p></td></tr><tr><td>on_call</td><td>bool</td><td>true, false</td><td>True if the user is currently on a call (including phone, voip, facetime, etc).</td></tr><tr><td>other_audio_playing</td><td>bool</td><td>true, false</td><td>True if audio is playing from another app on the system (example: Spotify, Youtube).</td></tr><tr><td>has_headphones</td><td>bool</td><td>true, false</td><td><p>True if the device is connected to headphones (regardless if audio is playing). Can be bluetooth or wired. </p><p></p><p>Does not include BT headsets used for phone calls; higher end headphones may temporarily report as headsets during a call, but will report as headphones at other times.</p></td></tr><tr><td>has_bt_headphones</td><td>bool</td><td>true, false</td><td><p>True if the device is connected to bluetooth headphones (regardless if audio is playing).</p><p></p><p>BT Headphones differentiate from BT headsets based on audio quality (headphones = BT A2DP, headsets = BT HFP). BT headphones being used for a phone call may temporarily report as headsets during a call, but will report as headphones at other times.</p></td></tr><tr><td>has_bt_headset</td><td>bool</td><td>true, false</td><td><p>True if the device is connected to a bluetooth headset.</p><p></p><p>Headphones differentiate from headsets based on audio quality (headphones = BT A2DP, headsets = BT HFP). BT headphones being used for a phone call may temporarily report as headsets during a call, but will report as headphones at other times.</p></td></tr><tr><td>has_wired_headset</td><td>bool</td><td>true, false</td><td>True if the device is connected to a wired headset or headphones (wired microphone, wired headphones, or both).</td></tr><tr><td>has_car_audio</td><td>bool</td><td>true, false</td><td><p>True if the device is connected to a car audio system.</p><p></p><p>Some cars may report as bluetooth headphones/headsets (and not car audio), depending on connection method.</p></td></tr><tr><td>has_watch</td><td>bool</td><td>true, false</td><td>True if the user has an watch paired to this device.</td></tr><tr><td>app_state</td><td>string</td><td>active, inactive, background, unknown</td><td>The applications state. See <a href="https://developer.apple.com/documentation/uikit/uiapplication/1623003-applicationstate">Apple Documentation</a> on meaning of each state.</td></tr><tr><td>foreground</td><td>bool</td><td>true, false</td><td>True if the app is rendering in the foreground. False if the app is running in the background.</td></tr><tr><td>Random number generation</td><td>na</td><td>na</td><td>Random number generation is available as <a href="../syntax-and-operators#random-number-generation">operators</a>.</td></tr><tr><td>timezone_gmt_offset</td><td>int</td><td>-18000</td><td>The device's timezone, expressed as an offset in seconds from GMT. For example, -5h from GMT returns -18000</td></tr><tr><td>location_permission</td><td>bool</td><td>true, false</td><td>True if the user has granted permission for this app to access location data.</td></tr><tr><td>location_permission_detailed</td><td>string</td><td>authorized_always, denied</td><td><p>The permission level this app has to access location data.</p><p></p><p>One of: not_determined, restricted, denied, authorized_always, authorized_when_in_use, unknown. See <a href="https://developer.apple.com/documentation/corelocation/clauthorizationstatus?language=objc">Apple docs for details</a>.</p></td></tr><tr><td>location_latitude</td><td>nullable float</td><td>43.642567</td><td>The latitude of this device. Can be nil of location not authorized. <a href="conditional-guides/locations-and-weather">See details</a>.</td></tr><tr><td>location_longitude</td><td>nullable float</td><td>-79.387054</td><td>The longitude of this device. Can be nil of location not authorized. <a href="conditional-guides/locations-and-weather">See details</a>.</td></tr><tr><td>location_city</td><td>nullable string</td><td>Toronto</td><td>The name of the city, from the device's current location. Can be nil if location not authorized, or if not in a city. <a href="conditional-guides/locations-and-weather">See details</a>.</td></tr><tr><td>location_region</td><td>nullable string</td><td>"ON" (for Ontario)</td><td>The short name of the province/state, from the device's current location. Can be nil if location not authorized, or if not in a region. <a href="conditional-guides/locations-and-weather">See details</a>.</td></tr><tr><td>location_country</td><td>nullable string</td><td>"CA" (for Canada)</td><td>The ISO country name, from the device's current location. Can be nil if location not authorized, or if not in a country. <a href="conditional-guides/locations-and-weather">See details</a>.</td></tr><tr><td>location_approx_latitude</td><td>nullable float</td><td>43.642567</td><td>The approximate latitude of this device, inferred from the device's IP. Does not require location permissions. Less accurate than GPS location, and may be incorrect.</td></tr><tr><td>location_approx_longitude</td><td>nullable float</td><td>-79.387054</td><td>The approximate longitude of this device, inferred from the device's IP. Does not require location permissions. Less accurate than GPS location, and may be incorrect.</td></tr><tr><td>location_approx_city</td><td>nullable string</td><td>Toronto</td><td>The name of the city, from the device's approximate location inferred from the device's IP. Does not require location permissions. Less accurate than GPS location, and may be incorrect.</td></tr><tr><td>location_approx_region</td><td>nullable string</td><td>"ON" (for Ontario)</td><td>The name of the short name of the province/state, from the device's approximate location inferred from the device's IP. Does not require location permissions. Less accurate than GPS location, and may be incorrect.</td></tr><tr><td>location_approx_country</td><td>nullable string</td><td>"CA" (for Canada)</td><td>The ISO country name, from the device's approximate location inferred from the device's IP. Does not require location permissions. Less accurate than GPS location, and may be incorrect.</td></tr><tr><td>weather_temperature</td><td>nullable float</td><td>22.5</td><td><p>The temperature in the user's location in celsius.</p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details and restrictions.</p></td></tr><tr><td>weather_apparent_temperature</td><td>nullable float</td><td>23.5</td><td><p>The apparent (feel like) temperature in the user's location in celsius.</p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details and restrictions.</p></td></tr><tr><td>weather_condition</td><td>nullable string</td><td>"Drizzle", "Clear", "Snow", etc</td><td><p>A string describing the weather conditions in the user's current location. </p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details, restrictions, and possible return values.</p></td></tr><tr><td>weather_cloud_cover</td><td>nullable float</td><td>0.05, 0.99</td><td><p>The percentage of the sky covered with clouds in the user's location.</p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details and restrictions.</p></td></tr><tr><td>is_daylight</td><td>string</td><td>"unknown", "daylight", "not_daylight"</td><td><p>Is it daylight in the user's location. </p><p></p><p>Uses the weather service to lookup local sunrise/sunset times. Consider using <a href="conditional-guides/working-with-dates">local time of day</a> if you only need time-of-day.</p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details and restrictions.</p></td></tr><tr><td>weather_approx_location_temperature</td><td>nullable float</td><td>22.5</td><td><p>The temperature in the user's approximate location, in celsius.</p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details and restrictions.</p></td></tr><tr><td>weather_approx_location_apparent_temperature</td><td>nullable float</td><td>23.5</td><td><p>The apparent (feel like) temperature in the user's approximate location, in celsius.</p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details and restrictions.</p></td></tr><tr><td>weather_approx_location_condition</td><td>string</td><td>"Drizzle", "Clear", "Snow", etc</td><td><p>A string describing the weather conditions in the user's approximate location. <a href="https://developer.apple.com/documentation/weatherkit/weathercondition">Possible values listed here</a>.</p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details, restrictions, and possible return values.</p></td></tr><tr><td>weather_approx_location_cloud_cover</td><td>nullable float</td><td>0.05, 0.99</td><td><p>The percentage of the sky covered with clouds in the user's approximate location.</p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details and restrictions.</p></td></tr><tr><td>approx_location_is_daylight</td><td>string</td><td>"unknown", "daylight", "not_daylight"</td><td><p>Is it daylight in the user's approximate location.</p><p></p><p>Uses the weather service to lookup local sunrise/sunset times. Consider using <a href="conditional-guides/working-with-dates">local time of day</a> if you only need time-of-day.</p><p></p><p>See the <a href="../conditional-guides/locations-and-weather#weather">Weather Guide</a> for details and restrictions.</p></td></tr><tr><td>contacts_permission</td><td>string</td><td>authorized, denied, etc</td><td>Has the user authorized access to contacts. Possible values: not_determined, restricted, denied, authorized, limited, unknown. <a href="https://developer.apple.com/documentation/contacts/cnauthorizationstatus?language=objc">Apple docs</a>.</td></tr><tr><td>camera_permission</td><td>string</td><td>authorized, denied, etc</td><td>Has the user authorized access to video capture. Possible values: not_determined, restricted, denied, authorized, unknown. <a href="https://developer.apple.com/documentation/avfoundation/avauthorizationstatus?language=objc">Apple docs</a>.</td></tr><tr><td>microphone_permission</td><td>string</td><td>authorized, denied, etc</td><td>Has the user authorized access to audio capture. Possible values: not_determined, restricted, denied, authorized, unknown. <a href="https://developer.apple.com/documentation/avfoundation/avauthorizationstatus?language=objc">Apple docs</a>.</td></tr><tr><td>notifications_permission</td><td>string</td><td>authorized, denied, etc</td><td>Has the user authorized the app to schedule and receive local and remote notifications. Possible values: not_determined, denied, authorized, provisional, ephemeral, unknown. <a href="https://developer.apple.com/documentation/usernotifications/unauthorizationstatus?language=objc">Apple docs</a>.</td></tr><tr><td>photo_library_permission</td><td>string</td><td>authorized, denied, etc</td><td>Has the user authorized access to read/write the photo library. Possible values: not_determined, denied, authorized, restricted, limited, unknown. <a href="https://developer.apple.com/documentation/photokit/phauthorizationstatus?language=objc">Apple docs</a>.</td></tr><tr><td>add_photo_permission</td><td>string</td><td>authorized, denied, etc</td><td>Has the user authorized access to add to the photo library. Possible values: not_determined, denied, authorized, restricted, limited, unknown. <a href="https://developer.apple.com/documentation/photokit/phauthorizationstatus?language=objc">Apple docs</a>.</td></tr><tr><td>calendar_permission</td><td>string</td><td>authorized_full, denied, etc</td><td>Has the user authorized access to calendar/events. Possible values: not_determined, denied, authorized_full, authorized_write_only, restricted, unknown. <a href="https://developer.apple.com/documentation/eventkit/ekauthorizationstatus?language=objc">Apple docs</a>.</td></tr><tr><td>reminders_permission</td><td>string</td><td>authorized_full, denied, etc</td><td>Has the user authorized access to reminders. Possible values: not_determined, denied, authorized_full, authorized_write_only, restricted, unknown. <a href="https://developer.apple.com/documentation/eventkit/ekauthorizationstatus?language=objc">Apple docs</a>.</td></tr><tr><td>bluetooth_permission</td><td>string</td><td>authorized, denied, etc</td><td>Has the user authorized access to bluetooth. Possible values: not_determined, denied, authorized, restricted, unknown. <a href="https://developer.apple.com/documentation/corebluetooth/cbmanagerauthorization?language=objc">Apple docs</a>.</td></tr><tr><td>canOpenUrl(string)</td><td>bool</td><td>true, false</td><td><p>This function returns if this app can open the provided url, which is useful for checking if other apps are installed. For example <code>canOpenUrl('spotify:')</code>. </p><p></p><p>See <a href="syntax-and-operators">full documentation</a>.</p></td></tr><tr><td>propertyEver(string, value)</td><td>bool</td><td>true, false</td><td><p>Returns if a property has ever had a given value, using a local database tracking prior observed values. </p><p></p><p>The value can be a string, int, float, bool or date. The value must match the named property's type or it will return false.</p><p></p><p><a href="../syntax-and-operators#propertyever-propnamestring-value">See docs for details</a>.</p></td></tr></tbody></table>

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com. Specifically, the GeoLite2 data is used for the `location_approx_*` properties.
