Built-in Properties
Critical moments comes with many properties and functions built in, which you can use for your conditional targeting
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...
platform
string
"iOS", "iPadOS"
The platform this is running on.
Note: for consistency we return "iPadOS" on all iPads, even OS versions before Apple started using the marketing name "iPadOS".
Note: iPad apps running on Mac return "iPadOS", not MacOS.
user_interface_idiom
string
"phone", "tablet", "tv", "car", "computer", "unknown"
The type of device. Always one of the listed example values.
Note: iPad apps running on Mac return "tablet", not "computer".
os_version
version string
"16.4.1"
The OS version number as a string.
Operators are available to compare version strings.
Note: iPad apps run on Mac will return the iPadOS simulator version they are running on, not the MacOS version of the host OS.
cm_version
version string
"1.2.3"
The version number of the CriticalMoments library on this client.
Operators are available to compare version strings.
device_manufacturer
string
Apple
The device manufacturer
device_model_class
string
"iPhone", "iPad" "iPod"
The manufacturer's description of the device type/class. See user_interface_idiom for a more general description of device type.
device_model
string
"iPhone13,3", "simulator", "iPad13,10"
The manufacturer's description string of this device.
List of Apple device models here.
device_model_version
nullable version string
"13.3", "14.2", nil
The floating point portion of device_model as a string. For example, for device_model "iPhone13,3" this field holds "13.3" Operators are available to compare version strings. Useful to find sets of devices, for example, to find iPhones newer than the iPhone 12: "device_model_class == "iPhone" && versionNumberComponent(device_model_version, 0) > 13". Yes, the "iPhone 12" has 13 in it’s device_model string… ask Apple not me.
Usually used in conjunction with device_model_class as value comparisons typically only makes sense within a class.
Nil on simulators, but populated on real hardware.
dark_mode
bool
true, false
True if the device is set to use the system’s "dark mode" style.
interface_orientation
string
"landscape", "portrait"
The orientation the main screen’s user interface is rendered in.
This may not match the physical orientation if the app only supports some orientations, or the user has rotation lock on.
For the orientation of the physical device regardless of interface rendering, see device_orientation.
device_orientation
string
"landscape", "portrait", "face_up", "face_down", "unknown"
The device’s physical orientation, regardless of the orientation the UI is rendered.
Returns face up/down if the device is nearly flat, such as sitting on a table.
Returns "unknown" on simulator or devices without accelerometers (computers).
For the orientation of the user interface rendering, see interface_orientation.
screen_width_points & screen_height_points
integer
853
The device screen size in "points" - https://blog.fluidui.com/designing-for-mobile-101-pixels-points-and-resolutions/
The height is always the greater of the two; these are rotation independent. For current orientation, see interface_orientation and device_orientation.
screen_width_pixels & screen_height_pixels
integer
2556
The device screen size in pixels.
The height is always the greater of the two; these are rotation independent. For current orientation, see interface_orientation and device_orientation.
screen_scale
float
1.0, 2.0, 3.0
screen_brightness
float
0.1, 0.9
The current brightness of the user's screen. Ranges from 0.0 to 1.0 inclusive.
screen_captured
bool
true, false
True if the user's screen is currently being captured (Airplay mirroring, screen recording, etc).
locale_language_code
string
"en", "es"
The language from the user-preferred locale
locale_country_code
string
"CA", "US"
The country from the user-preferred locale
locale_currency_code
string
"CAD", "USD", "EUR", "JPY"
The currency code from the user-preferred locale.
locale_language_direction
string
"RTL", "LTR"
Is the device's language right-to-left or left-to-right.
app_id
string
"io.criticalmoments.sampleapp"
The app’s ID.
On Apple devices this is the bundle identifier.
app_version
version string
"1.2.3.4"
The app version number as a string, such as "1.2.2".
Operators are available to compare version strings.
app_install_date
timestamp
See Working with Dates.
The timestamp this app was installed by the user.
If deleted and reinstalled, this will reflect the latest install.
app_start_time
timestamp
See Working with Dates.
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.
session_start_time
timestamp
See Working with Dates.
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.
is_debug_build
bool
true, false
True if this app was built as a debug build
device_battery_level
version string
0.88
Battery level ranges from 0.0 (fully discharged) to 1.0 (100% charged).
Returns 1.0 on devices that don’t have batteries (simulators, wired computers).
device_battery_state
string
"charging", "full", "unplugged", "unknown"
The battery state. Always one of the example values.
"full" indicates full and connected to power. To check if it's plugged in, you should check that it's "charging" or "full".
May return unknown on devices that don’t have batteries (simulators, wired computers)
device_low_power_mode
bool
true, false
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.
network_connection_type
string
"wifi", "cellular", "wired", "unkown"
Indicates the type of network connection the device currently uses.
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.
"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.
has_active_network
bool
true, false
True if the device has an working internet connection
low_data_mode
nullable bool
true, false, nil
Indicates if the user has low data mode enabled, indicating they want to save data.
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 (low_data_mode ?? false) using the nil coalesing operator ??.
expensive_network
bool
true, false
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".
https://developer.apple.com/documentation/network/2976891-nw_path_is_expensive
has_wifi_connection
bool
true, false
Indicates if the device is connected to a wifi network.
IMPORTANT: 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.
has_cell_connection
bool
true, false
True if the device is connected to a cellular network.
IMPORTANT: 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.
on_call
bool
true, false
True if the user is currently on a call (including phone, voip, facetime, etc).
other_audio_playing
bool
true, false
True if audio is playing from another app on the system (example: Spotify, Youtube).
has_headphones
bool
true, false
True if the device is connected to headphones (regardless if audio is playing). Can be bluetooth or wired.
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.
has_bt_headphones
bool
true, false
True if the device is connected to bluetooth headphones (regardless if audio is playing).
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.
has_bt_headset
bool
true, false
True if the device is connected to a bluetooth headset.
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.
has_wired_headset
bool
true, false
True if the device is connected to a wired headset or headphones (wired microphone, wired headphones, or both).
has_car_audio
bool
true, false
True if the device is connected to a car audio system.
Some cars may report as bluetooth headphones/headsets (and not car audio), depending on connection method.
has_watch
bool
true, false
True if the user has an watch paired to this device.
app_state
string
active, inactive, background, unknown
The applications state. See Apple Documentation on meaning of each state.
foreground
bool
true, false
True if the app is rendering in the foreground. False if the app is running in the background.
timezone_gmt_offset
int
-18000
The device's timezone, expressed as an offset in seconds from GMT. For example, -5h from GMT returns -18000
location_permission
bool
true, false
True if the user has granted permission for this app to access location data.
location_permission_detailed
string
authorized_always, denied
The permission level this app has to access location data.
One of: not_determined, restricted, denied, authorized_always, authorized_when_in_use, unknown. See Apple docs for details.
location_latitude
nullable float
43.642567
The latitude of this device. Can be nil of location not authorized. See details.
location_longitude
nullable float
-79.387054
The longitude of this device. Can be nil of location not authorized. See details.
location_city
nullable string
Toronto
The name of the city, from the device's current location. Can be nil if location not authorized, or if not in a city. See details.
location_region
nullable string
"ON" (for Ontario)
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. See details.
location_country
nullable string
"CA" (for Canada)
The ISO country name, from the device's current location. Can be nil if location not authorized, or if not in a country. See details.
location_approx_latitude
nullable float
43.642567
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.
location_approx_longitude
nullable float
-79.387054
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.
location_approx_city
nullable string
Toronto
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.
location_approx_region
nullable string
"ON" (for Ontario)
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.
location_approx_country
nullable string
"CA" (for Canada)
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.
weather_temperature
nullable float
22.5
The temperature in the user's location in celsius.
See the Weather Guide for details and restrictions.
weather_apparent_temperature
nullable float
23.5
The apparent (feel like) temperature in the user's location in celsius.
See the Weather Guide for details and restrictions.
weather_condition
nullable string
"Drizzle", "Clear", "Snow", etc
A string describing the weather conditions in the user's current location.
See the Weather Guide for details, restrictions, and possible return values.
weather_cloud_cover
nullable float
0.05, 0.99
The percentage of the sky covered with clouds in the user's location.
See the Weather Guide for details and restrictions.
is_daylight
string
"unknown", "daylight", "not_daylight"
Is it daylight in the user's location.
Uses the weather service to lookup local sunrise/sunset times. Consider using local time of day if you only need time-of-day.
See the Weather Guide for details and restrictions.
weather_approx_location_temperature
nullable float
22.5
The temperature in the user's approximate location, in celsius.
See the Weather Guide for details and restrictions.
weather_approx_location_apparent_temperature
nullable float
23.5
The apparent (feel like) temperature in the user's approximate location, in celsius.
See the Weather Guide for details and restrictions.
weather_approx_location_condition
string
"Drizzle", "Clear", "Snow", etc
A string describing the weather conditions in the user's approximate location. Possible values listed here.
See the Weather Guide for details, restrictions, and possible return values.
weather_approx_location_cloud_cover
nullable float
0.05, 0.99
The percentage of the sky covered with clouds in the user's approximate location.
See the Weather Guide for details and restrictions.
approx_location_is_daylight
string
"unknown", "daylight", "not_daylight"
Is it daylight in the user's approximate location.
Uses the weather service to lookup local sunrise/sunset times. Consider using local time of day if you only need time-of-day.
See the Weather Guide for details and restrictions.
contacts_permission
string
authorized, denied, etc
Has the user authorized access to contacts. Possible values: not_determined, restricted, denied, authorized, limited, unknown. Apple docs.
camera_permission
string
authorized, denied, etc
Has the user authorized access to video capture. Possible values: not_determined, restricted, denied, authorized, unknown. Apple docs.
microphone_permission
string
authorized, denied, etc
Has the user authorized access to audio capture. Possible values: not_determined, restricted, denied, authorized, unknown. Apple docs.
notifications_permission
string
authorized, denied, etc
Has the user authorized the app to schedule and receive local and remote notifications. Possible values: not_determined, denied, authorized, provisional, ephemeral, unknown. Apple docs.
photo_library_permission
string
authorized, denied, etc
Has the user authorized access to read/write the photo library. Possible values: not_determined, denied, authorized, restricted, limited, unknown. Apple docs.
add_photo_permission
string
authorized, denied, etc
Has the user authorized access to add to the photo library. Possible values: not_determined, denied, authorized, restricted, limited, unknown. Apple docs.
calendar_permission
string
authorized_full, denied, etc
Has the user authorized access to calendar/events. Possible values: not_determined, denied, authorized_full, authorized_write_only, restricted, unknown. Apple docs.
reminders_permission
string
authorized_full, denied, etc
Has the user authorized access to reminders. Possible values: not_determined, denied, authorized_full, authorized_write_only, restricted, unknown. Apple docs.
bluetooth_permission
string
authorized, denied, etc
Has the user authorized access to bluetooth. Possible values: not_determined, denied, authorized, restricted, unknown. Apple docs.
canOpenUrl(string)
bool
true, false
This function returns if this app can open the provided url, which is useful for checking if other apps are installed. For example canOpenUrl('spotify:').
See full documentation.
propertyEver(string, value)
bool
true, false
Returns if a property has ever had a given value, using a local database tracking prior observed values.
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.
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.
Last updated