Attributes are key-value pairs that you associate with your audience to help better target them with messages. Use attributes to target audiences with greater specificity than you would with tags.

Attributes extend the concept of tagsMetadata that you can associate with channels or named users for audience segmentation. Tags are generally descriptive terms indicating user preferences or other categorizations, e.g., wine_enthusiast or weather_alerts_los_angeles. Tags are case-sensitive. by adding comparison operators and values to audience expressions, helping you better evaluate your audience. Attributes can be set on ChannelsAn instance representing an entity addressable via the Airship service, e.g., an iOS device, email address, SMS number or web browser. The channel instance or channel object contains all relevant information about a channel, including metadata used for targeting, opt-in status, device-specific information, and, importantly, a unique identifier for the channel, the channel ID. and Named UsersA customer-provided identifier used for mapping multiple devices and channels to a specific individual. .

Consider the example below — you want to target fans of the actor Chris Pine. To accomplish this, you specify an audience of users with the tag chris_pine. Either a user has this tag, or not. Note: These API examples can also be used in the dashboard.

Tag audience:
   "audience": {
      "tag": "chris_pine"

But let’s say you wanted to target fans of All The Chrises: Chris Pine, Chris Evans, Chris Pratt, and Chris Hemsworth. With attributes, you can set your audience to target users whose favorite_actor attribute contains the value chris, and you will reach all the Chris fans.

Attributes audience:
   "audience": {
      "attribute": "favorite_actor",
      "operator": "contains",
      "value": "chris"

It’s a silly example, but hopefully you can begin to see the power of comparison operators for attributes.

Setting Attributes On Named Users

You can set attributes at both the channel and named user levels.

  • When you set an attribute on a named user, all the channels associated with the named user will also bear that attribute. When you remove a channel from a named user, Airship removes attributes set on the named user from that channel.

  • While you can set attributes on a channel, named users do not inherit these attributes from their associated channels. Setting attributes at the channel level can limit your flexibility when targeting audiences and the benefits of named users.

In general, we recommend that you store attributes at the named user level so you can take advantage of your attributes across any of the channels belonging to your users. Storing attributes at the named user level helps you build and maintain a cohesive relationship with your audience across any of their channels. Setting attributes at the channel level limits the scope of the attribute to that channel.

Using the example favorite_actor attribute contains the value chris, if you store the favorite_actor attribute at the named user level, you can target all contacts who are fans of Chrises over any of their channels. You can keep your audience up to date on Chris-related news, no matter which channels they use to communicate with you.

Use attributes to send to any channel associated with a named user
graph LR A[Named User
with Attributes] B[Attribute Selector] subgraph Audience C[App Message] D[SMS] E[Web Notification] end A --> B B -.-> C B -.-> D B -.-> E

If you store the favorite_actor attribute at the channel level, you can only target fans of Chrises on the specific channels bearing the favorite_actor attribute, limiting the scope of Chris-related communications.

Attributes at the channel level are limited to that channel
graph LR A[App Channel
with Attributes] B[Attribute Selector] subgraph Audience C[App Message] D[SMS] E[Web Push] end A --> B -.-> C

Named users also inherit a few default attributes from the last channel that was associated with them, helping keep your named users up to date with scheduling and locale information. These attributes appear in the user_attributes object.

  • ua_local_tz - The user’s time zone, e.g., “America/Los_Angeles”.
  • ua_country - The user’s ISO 3166 two-character country code, e.g., “US”.
  • ua_language - The user’s ISO 639-1 two-character language code, e.g., “en”.

Attribute Components and Variations

The components of an attribute:

  • Name: A human-friendly name to help you organize and identify your attributes in the Airship dashboard.
  • ID: The key that Airship uses to reference the attribute in our SDKs and API.
  • Type: The format of the attribute value — text, number (numeric and decimal), or date. See Attribute types on this page.
  • Value: Data provided by the SDK or set by you.

Airship supplies and automatically assigns a set of default attributes, based on data collected by the Airship SDKs. You can also define custom attributes and add predefined attributes.

Attribute Types

An attribute’s type determines the format of its value:

  • Text attributes use string values. When setting text attributes using a CSV, you do not need to wrap text attributes in quotes.
  • Number attributes take integers or float values. When setting number attributes, you can provide your value as an integer, float, or string.
  • Date attributes take ISO 8601 date-time formatted strings — YYYY-MM-DDTHH:MM:SS. You can set an offset by appending the date-time with +HH:MM (e.g., 2020-07-20T12:35:42+08:00). Date attributes are converted to and stored as UTC.

Different attribute types use different operators when targeting your audience. For text and number attributes, you evaluate attributes using equals, contains, less, greater, and is_empty operators. For date attributes, you use before, after, equals, or range (indicating the target attribute should fall between two dates that you provide).

Set different types of attributes
POST /api/channels/attributes HTTP/1.1
Authorization: Basic <App Auth>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

    "audience": {
        "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    "attributes": [
            "action": "set",
            "key": "favorite_food",
            "value": "cake"
            "action": "set",
            "key": "age",
            "value": 35
            "action": "set",
            "key": "birthdate",
            "value": "1985-07-14T00:00:00"

Set Up Your Project For Attributes

Before you can target using attributes, some setup work is required, and some steps must be performed by your mobile and web developers. You may also need to perform some server-side work if you want to set attributes or target audiences using our API.

  • Upgrade your SDKs — Required if you want to use default attributes or set attributes from the SDK
  • Define custom attributes or add predefined attributes
  • Set attributes on channels or named users by uploading a CSV in the dashboard or using SFTP, or from our SDKs or Channels API

Upgrade Your SDKs

You must upgrade to the listed minimum iOS and Android SDKs if you want to:

  • Use default attributes — Updating the SDK enables Airship to automatically set the default attributes for you. You can then use default attributes for targeting.
  • Set attributes from the SDK



If you are on an iOS SDK version prior to 12.1.0 and only want to upgrade for attributes, you can upgrade to 12.1.2, which includes patches since the initial attributes release.

We also support attributes in our latest major release, iOS SDK 13.0. Note, however, that our SDK 13.0 release splits the SDK into modules and requires additional development work. See the changelog and migration guide links in our iOS SDK 13.0 release note for details.



Airship Android SDK 12 was a major release, decoupling Airship channel registration from push functionality and providing support for attributes. We do not recommend upgrading unless you plan to use attributes and are able to perform the other necessary steps to complete the upgrade.

See the Airship Android SDK Migration Guide for details.

Add Attributes to Your Project


You can add custom and predefined attributes to your Airship project at any time, but you set attributes on your audience by uploading a CSV, or from our SDKs or Channels API.

You can create up to 250 attributes per project.

  1. Go to Audience » Attributes » Attribute List and click Create Attribute.

  2. Search to see if Airship has predefined the attribute you want to create. Search does not return predefined attributes that have been archived or have already been added. See: List of predefined attributes.

  3. Complete the attribute fields. You can only edit the name for predefined attributes.

    • Attribute ID: Letters, numbers, and underscores only. 128 characters maximum.
    • Name: All characters accepted. 64 characters maximum.
    • Type: Date, Text, or Number.

      • The attribute ID is the key that Airship uses to reference the attribute in our SDKs and API; we recommend using lower-case characters with underscores for the ID, e.g., my_text_attribute.

      • Attribute IDs are case sensitive. If attributes exist in an external system, make sure they are always the same case in both systems.

      • Names and IDs must be unique. You cannot edit the ID or type after you create a custom attribute.

  4. Click Add.

Set Attributes On Your Audience


You must define custom attributes or add predefined attributes in the dashboard before associating them with channels and named users. Trying to use a custom or predefined attribute that you haven’t yet set up in the dashboard will result in an error.

Use the attribute ID as the value for the key when setting or removing attributes. Set attributes on channels or named users by uploading a CSV in the dashboard or using SFTP, or from our SDKs or Channels API.

Set Attributes Using a CSV File

Follow the steps in the SFTP tutorial, or follow the steps below for CSV upload in the Airship dashboard. When using email or SMS identifiers in your CSV file, Airship registers new channels for addresses or MSISDN/sender combinations that are new to your project. Additional fields indicate opt-in statuses, so that you can send messages to new channels generated from your CSV upload.

  1. Prepare your CSV file using the guidelines in CSV Formatting Reference: Attributes.

  2. Go to Audience » Attributes » Upload Attribute Data. Click Download sample CSV file   to see a formatted file.

  3. Click Choose file and select your CSV.

  4. Click Upload. Your dashboard and SFTP uploads are listed in Audience » Attributes » Upload History.

Set Attributes From the SDK

To set or remove attributes on a channel or named user, use the attributes classes in our SDKs:

The code examples below show how to set attributes using the provided methods. See the iOS, Android and Web SDK docs for more details.

Android: Java
            .setAttribute("average_rating", 4.99)
            .setAttribute("last_product_purchased", "A1234567")

iOS: Swift
    let mutations = UAAttributeMutations()
    mutations.setNumber(4.99, forAttribute: "average_rating")
    mutations.setString("cauldron", forAttribute:"last_product_purchased")

iOS: Objective-C
    UAAttributeMutations *mutations = [UAAttributeMutations mutations];
    [mutations setNumber:@4.99 forAttribute:@"average_rating"];
    [mutations setString:@"cauldron" forAttribute:@"last_product_purchased"];
    [mutations removeAttribute:@"pending_purchase"];
    [[UAirship channel] applyAttributeMutations:mutations];

UA.then(function(sdk) {
     .set({last_product_purchased: "A1234567"})
     .then(result => console.log("Last product purchase attribute updated!"))
     .catch(err => console.error("An error occured while setting attributes: %s", err))

UA.then(function(sdk) {
   .then(result => console.log("Purchase pending attribute has been removed!"))
   .catch(err => console.error("An error occured while removing 1 attribute: %s", err))

Set Attributes From the API

You can set attribute values from external sources, e.g., CRM or data warehouse, using the Channels API.

Use the Set or Remove Attributes endpoint to set an attribute on, or remove an attribute from, a channel or named user.

Set two attributes on a channel and remove another:
POST /api/channels/attributes HTTP/1.1
Authorization: Basic <App Auth>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

    "audience": {
        "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    "attributes": [
            "action": "set",
            "key": "favorite_actor",
            "value": "chris_evans",
            "timestamp": "2019-09-19 12:00:00"
            "action": "remove",
            "key": "favorite_color",
            "timestamp": "2019-09-19 12:00:00"
            "action": "set",
            "key": "first_name",
            "value": "Roger",
            "timestamp": "2019-09-19 12:00:00"

Manage Attributes

Go to Audience » Attributes » Attribute List.

  • Your last created attribute is listed first.
  • Your total number of custom and predefined attributes is displayed next to Create Attribute.
  • You can filter the list by All, Default, and Custom. Custom includes your predefined attributes.
  • The Status column indicates whether an attribute is Active or Archived.
  • You can search for attributes by name or ID.

Edit Attributes

You can edit the names of custom and predefined attributes. You cannot edit an archived attribute — you must first change the status back to Active.

  1. Go to Audience » Attributes » Attribute List.
  2. Click   for an attribute.
  3. Edit the attribute name and click Save.

Archive/Unarchive Attributes

You can archive custom and predefined attributes.

  • Archiving an attribute removes it from your total count of attributes (maximum 250).
  • Archived predefined attributes will not appear in search when adding attributes to your project.
  • Archiving stops data collection for an attribute. Data collected prior to archiving is made available again when you change the status back to Active.
  1. Go to Audience » Attributes » Attribute List.
  2. Click   for an attribute to toggle its Archived/Active status.

Delete Custom Attributes

Contact Airship Support to delete custom attributes.

View Attributes Upload History

When you set attributes using a CSV file, the history is saved in Audience » Attributes » Upload History. The latest upload is listed first, with columns for:

  • File name
  • User name: The user who performed the upload in the dashboard
  • Source: Dashboard or SFTP
  • Upload date
  • Status: Processed, Processed with errors, Processing, or Failed

For status Processed with errors, click   to download the error list.

Target Your Audience Using Attributes

For messages sent from the dashboard, follow the steps in Target Specific Users. For the API, follow the steps here.

To target users based on attributes, use the attributes audience object, which consists of the attribute ID, comparison operator, attribute value, and an optional precision in the case of a DATE attribute.

Example push to a TEXT attribute:
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json

    "audience": {
        "attribute": "item_purchased",
        "operator": "contains",
        "value": "jeans"
    "device_types": [
    "notification": {
        "alert": "Hello from Airship"

See Attributes in our API reference for details and example requests.

Use boolean NOT or AND operators to create compound audience expressions. In the following example, the NOT operator gives you the same result as if you had used the “does not contain” operator via the UI.

See Compound Selector for details on using boolean audience operators.

    "NOT": {
        "attribute": "item_purchased",
        "operator": "contains",
        "value": "jeans"
    "AND": [
            "attribute": "size",
            "operator": "greater",
            "value": 12
            "attribute": "size",
            "operator": "less",
            "value": 15

Default Attributes

Airship default attributes.

Languageua_languageTextApp, Web“EN”
Language Countryua_countryTextApp, WebTwo-letter ISO country code like “DE”, or “Unknown”
Location Settingsua_location_settingsTextApp“true”/“false” value indicating if location services are enabled
iOS/Android App Versionua_app_versionTextApp“1051.c3eca0”, “957”
SDK Versionua_sdk_versionTextApp, Web“12.0.0-beta3” (Point version)
Device Modelua_device_modelTextApp“Pixel 3a”, “iPhone8,1”
Device OSua_device_osTextApp“13.1.2”, “10”
Carrierua_carrierTextApp“Verizon”, “AT\u0026T”, “Free”, “Google Fi”
Local Time Zoneua_local_tzTextApp, Web“Africa/Abidjan”
Browser Nameua_browser_nameTextWeb“chrome”, “firefox”
Browser Versionua_browser_versionTextWeb“chrome-77”, “firefox-69”
Browser Typeua_browser_typeTextWeb“mobile” or “desktop”
NDCua_ndcTextSMSThe 2- or 3-digit national destination code, commonly known in the US as the area code, e.g., 503. This attribute is country-specific and is only populated if the MSISDNThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device. has a discernible code.
Subdivisionua_subdivisionTextSMSThe ISO-3166 country and subdivision for the channel — state, province, etc e.g., US-OR.

Predefined Attributes

Airship predefined attributes.

First Namefirst_nameText
Last Namelast_nameText
Full Namefull_nameText
Region 1regionText
Mobile Phone Numbermobile_phoneNumber
Home Phone Numberhome_phoneNumber
Work Phone Numberwork_phoneNumber
Loyalty Tierloyalty_tierText
Account Creationaccount_creationDate
Email AddressemailText
Advertising ID (IDFA)advertising_idText

1. State or province.