About attributes

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.

{
   "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.

{
   "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.

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.

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.

• Default attributes are automatically set on your audience by Airship. See: List of default attributes.

• Predefined attributes are preformatted attributes that you can add to your project and then set on your audience. Predefined attributes ensure consistency across reports and Performance AnalyticsA customizable marketing intelligence tool that provides access to reports and graphs based on engagement data. . Examples: ID first_name for first name, and ID last_name for last name. See: List of predefined attributes.

• NPS survey attributes are based on data from your NPS (Net Promoter Score) SurveysQuestion-and-answer experiences used to collect and aggregate feedback or generate a net promoter score. They are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. . See also: About Surveys: Reporting.

• Custom attributes are attributes that you define and set on your audience.

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

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