Device Property Tags

This guide examines the hundreds of available Device Property Tags in detail.

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

  • 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”. If our system is unable to determine a device’s language settings, for example, 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.

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 Name Tag Group ID Valid Tags Sentinel Value
Timezone timezone Timezone Identifiers Unknown (UI) or NO_TIME_ZONE (API)
Notification Opt-in ua_opt_in "true" or "false" None available
Background Enabled ua_background_enabled "true" or "false" None available
Location Enabled ua_location_enabled "true" or "false"†* None available
iOS App Version ua_ios_app_version Any sanitized string** Unknown
Android App Version ua_android_app_version Any sanitized string** Unknown
Language ua_locale_country ISO 3166-1 (alpha-2 codes)*** Unknown
Language Country ua_locale_language ISO 639-1*** Unknown
iOS UA SDK Version ua_ios_sdk_version SDK version number Unknown
Android UA SDK Version ua_android_sdk_version SDK version number Unknown
iOS Version ua_ios_version iOS version number Unknown
Android Version ua_android_version Android version number Unknown
iOS Model ua_ios_model iOS Models Unknown
  • †: 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" }
  
  • *: The Location Enabled tag group only contains devices with SDK 6.0+.

  • **: Because 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

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

as invalid, presumably none of your iOS users are using the "pizzzzzza" version of your app, so no one will receive the message.

  • ***: Please see the Location section for details on location-based tags.

Timezone Identifiers

The list below is all of the timezone identifiers currently recognized by Urban Airship. Both the display name and API name are identical. Make sure to remember to use quotes around the tag when using the API.

Example:

{ "group": "timezone", "tag": "Africa/Addis_Ababa" }

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

Timezone (Display/API Name) UTC Offset UTC 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

Location

You’ll notice that both of our location-based device tag groups, ua_locale_language and ua_locale_country, contain the word “locale”. Before explaining precisely what these two groups specify, we should define device locale.

Locale is a device’s language/country specification. Both iOS and Android allow users to set device locale via a Settings page.

Example (iOS):

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

Example (Android):

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

This brings us to the actual tag groups ua_locale_language and ua_locale_country. The ua_locale_language tag group is used to specify the language-half of the locale. So to target the above two devices, we could use the following tag:

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

As mentioned in the table at the top of this page, the tag will be an ISO 639-1 code.

The tag group ua_locale_country is used to target the country-half of a device’s locale:

{ "group": "ua_locale_country", "tag": "US" }

The tag is an ISO 3166-1 Alpha-2 code.

Keep in mind that a device’s language and country settings imply nothing about the actual user’s language or location. As an English speaking citizen of the US, I could go into my phone’s settings and change my country to China and language to Arabic, and my device locale would reflect those changes. For that reason, it is best to think of locale_country and locale_language as useful approximations of a user’s location and language.

SDK Version

The tags for SDK version take the form #.#.X (e.g. 4.0.X). We do not allow targeting of specific patches, such as 4.0.1. When setting a tag while composing a message, searching for the SDK Version group will resolve any queries to specific patches to the nearest possible version. For example, searching for 4.0.1 will bring up 4.0.X as a result. When using the API, you must use the #.#.X format, or else 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 corresonding to each tag. For more information on the differences between SDK Versions, please see our Android and iOS SDK changelogs.

iOS SDK Versions:

iOS SDK Version (Display/API Name) Corresponding SDK Versions
1.0.X 1.0.0–1.0.7
1.1.X 1.1.0–1.1.5
1.2.X 1.2.0–1.2.2
1.3.X 1.3.0–1.3.7
1.4.X 1.4.0
2.0.X 2.0.0–2.0.4
2.1.X 2.1.0
3.0.X 3.0.0-3.0.4
4.0.X 4.0.0–4.0.4
5.0.X 5.0.0–5.0.3
5.1.X 5.1.0–5.1.1
6.0.X 6.0.0–6.0.2
6.1.X 6.1.0

Android SDK Versions:

Android SDK Version (Display/API Name) Corresponding Releases
0.9.X 0.9.1
1.0.X 1.0.0–1.0.9
1.1.X 1.1.0–1.1.6
2.0.X 2.0.0–2.0.5
2.1.X 2.1.0–2.1.4
3.0.X 3.0.0
3.1.X 3.1.0
3.2.X 3.2.0–3.2.3
3.3.X 3.3.0–3.3.2
4.0.X 4.0.0–4.0.4
5.0.X 5.0.0–5.0.3
5.1.X 5.1.0–5.1.6
6.0.X 6.0.0–6.0.2
6.1.X 6.1.0

Platform Version

Similar to the SDK Version tags, platform version tags take the form #.#.X (e.g. 1.6.X). We do not allow targeting of specific patches.

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

iOS Version (Display/API Name) Corresponding Releases
1.0.X 1.0–1.0.2
1.1.X 1.1–1.1.5
2.0.X 2.0–2.0.2
2.1.X 2.1
2.2.X 2.2–2.2.1
3.0.X 3.0–3.0.1
3.1.X 3.1–3.1.3
3.2.X 3.2–3.2.2
4.0.X 4.0–4.0.2
4.1.X 4.1
4.2.X 4.2.1–4.2.10
4.3.X 4.3–4.3.5
5.0.X 5.0–5.0.1
5.1.X 5.1–5.1.1
6.0.X 6.0–6.0.2
6.1.X 6.1–6.1.6
7.0.X 7.0–7.0.6
7.1.X 7.1–7.1.2
8.0.X 8.0–8.0.2
8.1.X 8.1–8.1.3
8.2.X 8.2
8.3.X 8.3
Android Version (Display/API Name) Code Name Corresponding Releases
1.5.X Cupcake 1.5
1.6.X Donut 1.6
2.0.X Eclair 2.0–2.0.1
2.1.X Eclair 2.1
2.2.X Froyo 2.2–2.2.3
2.3.X Gingerbread 2.3–2.3.7
3.0.X Honeycomb 3.0
3.1.X Honeycomb 3.1
3.2.X Honeycomb 3.2–3.2.6
4.0.X Ice Cream Sandwich 4.0–4.0.4
4.1.X Jelly Bean 4.1–4.1.2
4.2.X Jelly Bean 4.2–4.2.2
4.3.X Jelly Bean 4.3–4.3.1
4.4.X KitKat 4.4–4.4.4
5.0.X Lollipop 5.0–5.0.2
5.1.X Lollipop 5.1–5.1.1

iOS Models

Below is a list of valid iOS model tags. The column on the left is the Display Name, or what will appear in the UI tag selector when you choose the audience type Target Specific Users, and the column on the left is the key used to refer to the tag in the API.

Display Name API Name
32-bit Simulator i386
64-bit Simulator x86_64
iPod Touch 1 iPod1,1
iPod Touch 2 iPod2,1
iPod Touch 3 iPod3,1
iPod Touch 4 iPod4,1
iPod Touch 5 iPod5,1
iPhone iPhone1,1
iPhone 3G iPhone1,2
iPhone 3GS iPhone2,1
iPad 1 iPad1,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 4S iPhone4,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 Plus iPhone7,1
iPhone 6 iPhone7,2

Common Segments

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

Looking at the list 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 version. We can create a segment that groups these tags together:

iPad 2:

{
   "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" }
      ]
   }
}

Here is 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" }
             ]
          }
       }'

We provide appropriate 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" }
      ]
   }
}