Target Your Audience Using Attributes

Attributes are key-value pairs that can be associated with a user or device for the purposes of audience targeting. Attributes are a new way to target your Airship users with complex expressions for fine-grained audience control.

Welcome to the beta program for Airship Attributes! Attributes extend the concept of a tag by adding a comparison operator and a value to the audience expression, allowing you to more carefully evaluate users for inclusion in your audience.


Attributes are currently a beta feature. If you wish to participate in the beta program, please complete our signup form.

Consider the example below — you want to target fans of the actor Chris Pine. To accomplish this, you are targeting all users with the tag chris_pine. Either a user has this tag, or not.

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"

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

In our initial beta releases, we are supporting Text and Number (numeric and decimal) attribute types only. You can evaluate provided attribute values using the operators equals, contains, less, greater, and is_empty.

In a future release, we will introduce the Date attribute type and additional operators.

Tutorial Overview

In order to begin using attributes, there is some setup work to be done by your mobile and web developers and possibly on the server side if you wish to target your audience via our API. In this tutorial, we’ll take you through the following steps:

  • Upgrade your SDKs
  • Define your attributes (UI only)
  • Set attributes on user channels (SDK and/or API)
  • Target your audience using attributes (UI and/or API)

Upgrade Mobile and Web SDKs

To set attributes on a user from a mobile device or web browser, you will need the latest Airship SDKs in order to access the new attribute classes.


The new Airship Android SDK is 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.



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

Attributes are also supported in our latest major release, iOS SDK 13.0. Note, however, that our 13.0 SDK release splits the SDK into modules and requires additional development work. See the migration guide linked from our release note for details.



Define Custom Attributes

Any attribute that you define in the dashboard is considered a custom attribute. For a list of default attributes, see Default Attributes below. To define your attributes, head to your project in the Airship dashboard.


You can define attributes in your Airship project at any time, but setting an attribute’s value for a user takes place either from our mobile/web SDKs or our REST API.

To define an attribute you will provide two items: the Name and Attribute ID. The Name of the attribute is used to organize and identify your attributes on the Airship dashboard and has no functional significance beyond this role. The Attribute ID is the key that corresponds to a specific text or number value of an attribute.

Examples for setting attributes are included below.


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

  1. Go to Audience » Attributes and click Create Attribute.
  2. Complete the attribute fields. Names and IDs must be unique. You cannot edit the ID or type after you create the attribute.
    • Name: All characters accepted. 64 characters maximum.
    • Attribute ID:
      Text Letters, numbers, and underscores only. 128 characters maximum.
      • Integers or decimals only.
      • For values that exceed ten thousandths, Airship rounds the value, based on the fifth digit after the decimal point.
      • Maximum values and precision before and after the decimal point:
      Maximum valuePrecision
      999 999 999 999 999N/A
      99 999 999 999 9990.1
      9 999 999 999 9990.01
      999 999 999 9990.001
      99 999 999 9990.0001
    • Type: Text or Number.
  3. Click Add.

Manage Custom Attributes

Go to Audience » Attributes to view a list of your custom and default attributes.

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


You can edit the name of a custom attribute. You cannot edit an archived attribute — you must first change the status back to Active.

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

Archive / Unarchive

You can archive custom attributes. 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.
  2. Click for an attribute to toggle its Archived/Active status.


Please contact Airship Support to delete custom attributes.

Set Attributes On a Channel

Attributes must be defined in the UI before using them in an API request. Use of an undefined attribute will result in an error. Once defined, use the attribute ID as the value for the key when setting or removing attributes.

Set attributes on a channel either from our SDKs or our Channels API.

Set Attributes From the SDK

To set attribute values or remove attributes on a channel, use the 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

In addition to mobile-specific attributes that you can set via our SDKs, you may wish to populate attribute values from external sources, e.g., CRM or data warehouse. Set these values with the Channels API.

Use the /channels/attributes endpoint to perform either the set or remove action on an attribute, specifying the channel ID in the audience object.


The Attributes API is currently in beta and not documented in our API reference.

Example: 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"

Request Parameters:

  • action — Required. Must be either set or removed.
  • key — Required. String, 255 characters maximum. The attributes key/name.
  • value — Required for set action. String (max length 255 characters). The value to set the attribute.
  • timestamp — Optional. An ISO 8601 timestamp when the attribute changed.

Target Your Audience Using Attributes

After you create attributes in the dashboard, you can use them to target your audience when sending messages in the dashboard or the API.


To target users based on attributes, use an audience selector that describes the attribute name, the comparison operator, and the value associated with the 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"

Request Parameters:

  • audience: Object, an audience selector.
  • attribute: String, the attribute ID that you entered when creating the attribute, or the ID for a default attribute.
  • operator: String, one of:
    • equals— Case insensitive when used with text attributes.
    • contains— Case insensitive when used with text attributes.
    • less
    • greater
    • is_empty— Evaluates to True if a channel does not have the attribute value.


Use boolean NOT or AND operators to create compound audience expressions:

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


In the Audience step in a Message or A/B Test:

  1. Select Target Specific Users.

  2. Enter an attribute name or ID in the search field, then click to select from the listed results. To filter results, click and select Attributes. You can select a filter before or after entering a search term.

  3. Set operator determining how you want to evaluate the attribute.

  4. (Optional) Click Add another target to add more attributes.


    You can add multiple attributes, but you cannot combine attributes with any other data types, e.g. tags, device properties. Note: Restrictions on combining attributes with other audience selectors will be lifted when the feature is generally available.

  5. Select ALL/ANY to determine how to evaluate multiple attributes.

    • ALL = all criteria must be met (boolean AND)
    • ANY = any criteria must be met (boolean OR)

Now you can complete the remaining steps in the composer.

Default Attributes

Airship default attributes. Currently only the app channel is supported. Web attributes will be available in a forthcoming web SDK release.

NameIDRelated ChannelsExample
Languageua_languageApp, Web“EN”
Language Countryua_countryApp, WebTwo-letter ISO country code like “DE”, or “Unknown”
Location Settingsua_location_settingsApp“true”/“false” value indicating if location services are enabled
iOS/Android App Versionua_app_versionApp“1051.c3eca0-master”, “957”
SDK Versionua_sdk_versionApp, Web“12.0.0-beta3” (Point version)
Device Modelua_device_modelApp“Pixel 3a”, “iPhone8,1”
Device OSua_device_osApp“13.1.2”, “10”
Carrierua_carrierApp“Verizon”, “AT\u0026T”, “Free”, “Google Fi”
Local Time Zoneua_local_tzApp, Web“Africa/Abidjan”
Browser Nameua_browser_nameWeb“chrome”, “firefox”
Browser Versionua_browser_versionWeb“chrome-77”, “firefox-69”
Browser Typeua_browser_typeWeb“mobile” or “desktop”