Device Property Tags

Urban Airship automatically collects data from your users’ devices, storing them as device properties. Device property tags are used to target specific users.

Collected Properties

Mobile apps and web browsers

Language
Language country
Time zone settings

Mobile apps only

iOS device model
iOS/Android app version
Location settings

Web browsers only

Browser name

Browser version

Browser type

Web SDK version

Opt-In Properties

Mobile apps only

Notification opt-in status
Background push status
Location enabled status

Tag Groups

Using device property tags, you can target users based on:

Language settings Timezone settings Location settings iOS/Android app version Notification opt-in status Background push status iOS device model

Each of these categories corresponds to a UA-generated tag group. The table below gives the following details for each group:

UI Name
How the tag group is displayed within the dashboard.
Tag Group ID
The ID used to refer to the tag group in the API.
Valid Tags
The tags contained within the tag group.
Sentinel Value
A special tag that is equivalent to "unknown".
Note

Example: If our system is unable to determine a device's language settings, the device will receive an "Unknown" tag in the "ua_locale_language" tag group. You could target such devices like so:

{ "group": "ua_locale_language", "tag": "Unknown" }
This push goes to all devices with unknown language settings.
Note

There are no sentinel values for Background Enabled, Location Enabled, or Notification Opt-in; every device will be tagged with either "true" or "false" for each of these groups.

Sentinel values will be presented as Unknown, both in the UI and API, with the exception of Timezone. Due to legacy reasons, the sentinel value for Timezone will display as Unknown in the UI but must be referred to as "NO_TIME_ZONE" via the API, e.g.:

{ "group": "timezone", "tag": "NO_TIME_ZONE" }
UI NameTag Group IDValid TagsSentinel Value
TimezonetimezoneTime zoneUnknown (UI) or NO_TIME_ZONE (API)
Notification Opt-inua_opt_in"true" or "false"None available
Background Enabledua_background_enabled"true" or "false"1None available
Location Enabledua_location_enabled"true" or "false"1, 2None available
iOS App Versionua_ios_app_versionAny sanitized string3Unknown
Android App Versionua_android_app_versionAny sanitized string3Unknown
Languageua_locale_language4ISO 639-1Unknown
Language Countryua_locale_country4ISO 3166-1 (alpha-2 codes)Unknown
iOS UA SDK Versionua_ios_sdk_versionSDK version numberUnknown
Android UA SDK Versionua_android_sdk_versionSDK version numberUnknown
iOS Versionua_ios_versioniOS version numberUnknown
Android Versionua_android_versionAndroid version numberUnknown
iOS Modelua_ios_modeliOS ModelUnknown

1 Note that when pushing to these tags via the API, you use a string that represents a Boolean value, not an actual Boolean. In other words, the valid tags are "true" and "false" rather than true and false. For example:

    { "group": "ua_background_enabled", "tag": "true" }
    

2 The Location Enabled tag group only contains devices with SDK 6.0+.

3Because we cannot check whether a string describing your app version is correct, the iOS App Version and Android App Version tag groups will accept any sanitized string as valid. However, a push will only reach your users if you use a valid version string for your app. For example, while the API will not flag a push to the following as invalid, presumably none of your iOS users are using the "pizzzzzza" version of your app, so no one will receive the message:

    { "tag":  "pizzzzzza", "group": "ua_ios_app_version" }
    

4 Please see Locale below.

Time Zone

A time zone (timezone) tag is identical to its UI name.

Note

This is not a full list of possible device time zones. If a device has a time zone setting that is not listed below, our system will attempt to resolve it to the nearest available time zone, then tag the device accordingly.

Tip

Make sure to use quotes around the tag when using the API. Example:

{ "group": "timezone", "tag": "Africa/Addis_Ababa" }
Time Zone Tag / UI NameUTC OffsetUTC DST Offset
Africa/Addis_Ababa+03:00+03:00
Africa/Harare+02:00+02:00
Africa/Lagos+01:00+01:00
America/Argentina/Buenos_Aires-03:00-03:00
America/Bogota-05:00-05:00
America/Caracas-04:30-04:30
America/Chicago (Central time zone)-06:00-05:00
America/Costa_Rica-06:00-06:00
America/Denver (Mountain time zone)-07:00-06:00
America/Halifax-04:00-03:00
America/Juneau (Alaska time zone)-09:00-08:00
America/Lima-05:00-05:00
America/Los_Angeles (Pacific time zone)-08:00-07:00
America/New_York (Eastern time zone)-05:00-04:00
America/Phoenix-07:00-07:00
America/Santiago-03:00-03:00
America/Sao_Paolo-03:00-02:00
Asia/Bangkok+07:00+07:00
Asia/Dhaka+06:00+06:00
Asia/Dubai+04:00+04:00
Asia/Hong_Kong+08:00+08:00
Asia/Jakarta+07:00+07:00
Asia/Karachi+05:00+05:00
Asia/Kolkata+05:30+05:30
Asia/Manila+08:00+08:00
Asia/Seoul+09:00+09:00
Asia/Singapore+08:00+08:00
Asia/Tehran+03:30+04:30
Asia/Tokyo+09:00+09:00
Asia/Vladivostok+10:00+10:00
Australia/Adelaide+09:30+10:30
Australia/Brisbane+10:00+10:00
Australia/Sydney+10:00+11:00
Etc/GMT+00:00+00:00
Europe/Istanbul+02:00+03:00
Europe/Lisbon+00:00+01:00
Europe/London+00:00+01:00
Europe/Moscow+03:00+03:00
Europe/Paris+01:00+02:00
Pacific/Auckland+12:00+13:00
Pacific/Honolulu (Hawaii time zone)-10:00-10:00
UTC+00:00+00:00

SDK Version

SDK version tags are in format #.#.X, e.g., 4.0.X. We do not allow targeting of specific patches, such as 4.0.1.

When setting a tag, searching for the SDK version group will resolve any queries of specific patches to the nearest possible version. For example, searching for 4.0.1 will return 4.0.X as a result. When using the API, you must use the #.#.X format or the push will not reach your audience. Example:

{ "tag": "4.0.X", "group": "ua_ios_version" }

The tables below show the available SDK version tags for both iOS and Android, along with with the range of SDK versions corresponding to each tag. For more information about the differences between SDK Versions, please see our Android and iOS SDK changelogs.

iOS

An SDK version tag is identical to its UI name.

iOS SDK Version Tag / UI NameSDK Versions
1.0.X1.0.0 – 1.0.7
1.1.X1.1.0 – 1.1.5
1.2.X1.2.0 – 1.2.2
1.3.X1.3.0 – 1.3.7
1.4.X1.4.0
2.0.X2.0.0 – 2.0.4
2.1.X2.1.0
3.0.X3.0.0 - 3.0.4
4.0.X4.0.0 – 4.0.4
5.0.X5.0.0 – 5.0.3
5.1.X5.1.0 – 5.1.1
6.0.X6.0.0 – 6.0.2
6.1.X6.1.0

Android

An SDK version tag is identical to its UI name.

Android SDK Version Tag / UI NameSDK Versions
0.9.X0.9.1
1.0.X1.0.0 – 1.0.9
1.1.X1.1.0 – 1.1.6
2.0.X2.0.0 – 2.0.5
2.1.X2.1.0 – 2.1.4
3.0.X3.0.0
3.1.X3.1.0
3.2.X3.2.0 – 3.2.3
3.3.X3.3.0 – 3.3.2
4.0.X4.0.0 – 4.0.4
5.0.X5.0.0 – 5.0.3
5.1.X5.1.0 – 5.1.6
6.0.X6.0.0 – 6.0.2
6.1.X6.1.0

Platform Version

Platform version tags are in format #.#.X, e.g., 1.6.X. We do not allow targeting of specific patches, such as 1.6.6.

For more information about the differences between various Android and iOS versions, please see Android version history and iOS version history.

iOS

A platform version tag is identical to its UI name.

iOS Platform Version Tag / UI NameRelease Versions
1.0.X1.0 – 1.0.2
1.1.X1.1 – 1.1.5
2.0.X2.0 – 2.0.2
2.1.X2.1
2.2.X2.2 – 2.2.1
3.0.X3.0 – 3.0.1
3.1.X3.1 – 3.1.3
3.2.X3.2 – 3.2.2
4.0.X4.0 – 4.0.2
4.1.X4.1
4.2.X4.2.1 – 4.2.10
4.3.X4.3 – 4.3.5
5.0.X5.0 – 5.0.1
5.1.X5.1 – 5.1.1
6.0.X6.0 – 6.0.2
6.1.X6.1 – 6.1.6
7.0.X7.0 – 7.0.6
7.1.X7.1 – 7.1.2
8.0.X8.0 – 8.0.2
8.1.X8.1 – 8.1.3
8.2.X8.2
8.3.X8.3

Android

A platform version tag is identical to its UI name.

Android Platform Version Tag / UI NameCode NameRelease Versions
1.5.XCupcake1.5
1.6.XDonut1.6
2.0.XEclair2.0 – 2.0.1
2.1.XEclair2.1
2.2.XFroyo2.2 – 2.2.3
2.3.XGingerbread2.3 – 2.3.7
3.0.XHoneycomb3.0
3.1.XHoneycomb3.1
3.2.XHoneycomb3.2 – 3.2.6
4.0.XIce Cream Sandwich4.0 – 4.0.4
4.1.XJelly Bean4.1 – 4.1.2
4.2.XJelly Bean4.2 – 4.2.2
4.3.XJelly Bean4.3 – 4.3.1
4.4.XKitKat4.4 – 4.4.4
5.0.XLollipop5.0 – 5.0.2
5.1.XLollipop5.1 – 5.1.1

iOS Model

A model tag's UI name appears in the dashboard when using Target Specific Users or Target Specific Users: In-App Automation.

UI NameModel Tag
32-bit Simulatori386
64-bit Simulatorx86_64
iPod Touch 1iPod1,1
iPod Touch 2iPod2,1
iPod Touch 3iPod3,1
iPod Touch 4iPod4,1
iPod Touch 5iPod5,1
iPhoneiPhone1,1
iPhone 3GiPhone1,2
iPhone 3GSiPhone2,1
iPad 1iPad1,1
iPad 2 (Wifi)iPad2,1
iPad 2 (Wifi/GSM)iPad2,2
iPad 2 (Wifi/CDMA)iPad2,3
iPad 2 (Wifi 16GB)iPad2,4
iPad Mini (Wifi)iPad2,5
iPad Mini (Wifi/GSM)iPad2,6
iPad Mini (Wifi/CDMA)iPad2,7
iPad 3 (Wifi)iPad3,1
iPad 3 (Wifi/CDMA)iPad3,2
iPad 3 (Wifi/GSM)iPad3,3
iPad 4 (Wifi)iPad3,4
iPad 4 Gen (Wifi/GSM)iPad3,5
iPad 4 Gen (Wifi/CDMA)iPad3,6
iPad Air (Wifi)iPad4,1
iPad Air (Wifi/Cellular)iPad4,2
iPad Air (Wifi/Cellular China)iPad4,3
iPad Mini 2 (Wifi)iPad4,4
iPad Mini 2 (Wifi/Cellular)iPad4,5
iPad Mini 2 (Wifi/Cellular China)iPad4,6
iPad Mini 3 (Wifi)iPad4,7
iPad Mini 3 (Wifi/Cellular)iPad4,8
iPad Mini 3 (Wifi/Cellular China)iPad4,9
iPad Air 2 (Wifi)iPad5,3
iPad Air 2 (Wifi/Cellular)iPad5,4
iPhone 4 (GSM)iPhone3,1
iPhone 4 (CDMA)iPhone3,3
iPhone 4SiPhone4,1
iPhone 5 (GSM)iPhone5,1
iPhone 5 (CDMA)iPhone5,2
iPhone 5c (CDMA/GSM)iPhone5,3
iPhone 5c (EMEA)iPhone5,4
iPhone 5s (CDMA/GSM)iPhone6,1
iPhone 5s (EMEA)iPhone6,2
iPhone 6 PlusiPhone7,1
iPhone 6iPhone7,2

Common Segments

Many use cases do not require the granularity of targeting devices by cellular technologies, e.g., CDMA/ or GSM. To avoid having to select each tag when you just want to push to a certain device, you can create segments via the API that group the related tags together.

iPad 2

Looking at the iOS Model table above, the first device that encompasses multiple tags is the iPad 2, which has separate tags for the Wifi, Wifi/GSM, Wifi/CDMA, and Wifi 16GB versions. You can create a segment that groups these tags together.

{
   "display_name": "iPad 2 - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPad2,1", "group": "ua_ios_model" },
         { "tag": "iPad2,2", "group": "ua_ios_model" },
         { "tag": "iPad2,3", "group": "ua_ios_model" },
         { "tag": "iPad2,4", "group": "ua_ios_model" }
      ]
   }
}

The corresponding cURL request:

curl https://go.urbanairship.com/api/segments \
   -X POST \
   -u "<AppKey>:<MasterSecret>" \
   -H "Content-Type: application/json" \
   -d '{
          "display_name": "iPad 2 - UA Generated",
          "criteria": {
             "OR": [
                { "tag": "iPad2,1", "group": "ua_ios_model" },
                { "tag": "iPad2,2", "group": "ua_ios_model" },
                { "tag": "iPad2,3", "group": "ua_ios_model" },
                { "tag": "iPad2,4", "group": "ua_ios_model" }
             ]
          }
       }'

Additional Models

JSON payloads for the remaining iOS devices that encompass multiple tags.

iPad Mini

{
   "display_name": "iPad Mini - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPad2,5", "group": "ua_ios_model" },
         { "tag": "iPad2,6", "group": "ua_ios_model" },
         { "tag": "iPad2,7", "group": "ua_ios_model" }
      ]
   }
}

iPad 3

{
   "display_name": "iPad 3 - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPad3,1", "group": "ua_ios_model" },
         { "tag": "iPad3,2", "group": "ua_ios_model" },
         { "tag": "iPad3,3", "group": "ua_ios_model" }
      ]
   }
}

iPad 4

{
   "display_name": "iPad 4 - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPad3,4", "group": "ua_ios_model" },
         { "tag": "iPad3,5", "group": "ua_ios_model" },
         { "tag": "iPad3,6", "group": "ua_ios_model" }
      ]
   }
}

iPad Air

{
   "display_name": "iPad Air - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPad4,1", "group": "ua_ios_model" },
         { "tag": "iPad4,2", "group": "ua_ios_model" },
         { "tag": "iPad4,3", "group": "ua_ios_model" }
      ]
   }
}

iPad Mini 2

{
   "display_name": "iPad Mini 2 - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPad4,4", "group": "ua_ios_model" },
         { "tag": "iPad4,5", "group": "ua_ios_model" },
         { "tag": "iPad4,6", "group": "ua_ios_model" }
      ]
   }
}

iPad Mini 3

{
   "display_name": "iPad Mini 3 - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPad4,7", "group": "ua_ios_model" },
         { "tag": "iPad4,8", "group": "ua_ios_model" },
         { "tag": "iPad4,9", "group": "ua_ios_model" }
      ]
   }
}

iPad Air 2

{
   "display_name": "iPad Air 2 - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPad5,3", "group": "ua_ios_model" },
         { "tag": "iPad5,4", "group": "ua_ios_model" }
      ]
   }
}

iPhone 4

{
   "display_name": "iPhone 4 - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPhone3,1", "group": "ua_ios_model" },
         { "tag": "iPhone3,3", "group": "ua_ios_model" }
      ]
   }
}

iPhone 5

{
   "display_name": "iPhone 5 - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPhone5,1", "group": "ua_ios_model" },
         { "tag": "iPhone5,2", "group": "ua_ios_model" }
      ]
   }
}

iPhone 5c

{
   "display_name": "iPhone 5c - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPhone5,3", "group": "ua_ios_model" },
         { "tag": "iPhone5,4", "group": "ua_ios_model" }
      ]
   }
}

iPhone 5s

{
   "display_name": "iPhone 5s - UA Generated",
   "criteria": {
      "OR": [
         { "tag": "iPhone6,1", "group": "ua_ios_model" },
         { "tag": "iPhone6,2", "group": "ua_ios_model" }
      ]
   }
}

Locale

A device's locale is determined by its language and country settings. Target a specific locale via tag groups ua_locale_language and ua_locale_country.

Warning

Keep in mind that a device's language and country settings imply nothing about the user's actual language or location. E.g., an English speaking citizen of the US could set the phone's country to China and language to Arabic, and the device locale would reflect those changes.

It is best to think of ua_locale_country and ua_locale_language as useful approximations only.

Device Settings

On iOS, the locale is a combination of the iPhone Language and Region settings. Converting the example in the image below using ISO standards, this iPhone has a locale of en_US.


With Android devices, you choose the language/country combination together. Unlike iOS, there are no separate menus for region and language. Translating the information in the image below using ISO standards, we have another device with locale en_US.

Example

The ua_locale_language tag group is used to specify the language-half of the locale. To target the two example devices in Device Settings above, use the tag en:

{ "group": "ua_locale_language", "tag": "en" }