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

Attributes extend the concept of tagsMetadata that you can associate with channels or named users for audience segmentation. Generally, they are 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.

 Warning

If you want to target users based on a unique user ID or other external identifier, do not use custom attributes. Instead, target Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. .

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 example, text and number attributes can be evaluated using equals, contains, less, greater, and is_empty operators. For date attributes, you can 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"
        }
    ]
}