Set Up and Manage Attributes

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.

Learn more in the Attributes feature guide.

Airship supplies and automatically assigns a set of default attributes for you. You can also define custom attributes. Custom 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 particular user. .

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 custom attributes from the SDK
  • Define custom attributes in the dashboard
  • 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 custom attributes from the SDK

iOS

 Important

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.

Android

 Important

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.

Define Custom Attributes

After you define custom attributes in the dashboard, you can then set them 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 particular user. .

 Important

You can define attributes in your Airship project at any time, but you can only set attribute values for users from our mobile/web SDKs or our REST API.

When defining an attribute you will provide two items: the Name and Attribute ID. The name of the attribute is a human-friendly name to help you organize and identify your attributes in the Airship dashboard. 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.

See examples for setting attributes below.

  1. Go to Audience » Attributes » Attribute List 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: Letters, numbers, and underscores only. 128 characters maximum.
    • Type: Date, Text, or Number.
       Important

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

  3. Click Add.

Set Attributes On Your Audience

You must define custom attributes in the dashboard before associating them with channels and named users. Trying to use an attribute that you haven’t defined yet will result in an error. After defining attributes, 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
UAirship.shared().getChannel().editAttributes()
            .setAttribute("average_rating", 4.99)
            .setAttribute("last_product_purchased", "A1234567")
            .removeAttribute("purchase_pending")
            .apply();

iOS: Swift
    let mutations = UAAttributeMutations()
    mutations.setNumber(4.99, forAttribute: "average_rating")
    mutations.setString("cauldron", forAttribute:"last_product_purchased")
    mutations.removeAttribute("purchase_pending")
    UAirship.channel()?.apply(mutations)

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];

Web
UA.then(function(sdk) {
   sdk.channel.attributes
     .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) {
 sdk.channel.attributes
   .remove("purchase_pending")
   .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 Custom Attributes

Go to Audience » Attributes » Attribute List 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.

Edit Custom Attributes

You can edit the attribute name only. 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 Custom Attributes

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 » 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

 Important

Attributes are a new feature in Airship. Some aspects of the feature are under development as a part of our beta program. If you want to participate in the beta program, complete our signup form.

Currently in beta:

  • Targeting your audience using attributes
    • In the API:
      • You can target text, number, and date attributes.
      • Attributes can be combined with tags and audience lists.
    • In the dashboard:
      • You can target text and number attributes only.
      • You can combine multiple attributes, but attributes cannot be combined with other data types, e.g., tags and audience lists.

See our API Reference:

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 name, 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": [
        "ios",
        "android",
        "web"
    ],
    "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.

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”