Airship Attributes Beta

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.

 Important

Custom channel 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"
   }
}

OK, it's a silly example, but hopefully you can begin to see the power of comparison operators for attributes. In this first beta release, we are supporting Text attribute types only, which means you can evaluate text strings that equal / do not equal or contain / do not contain the value you provide.

In future releases, we will introduce Number and Date attribute types, with operators like greater than, less than, before, after, etc.

Tutorial Overview

In order to begin using attributes, there is some setup work to be done by your mobile 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 mobile 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 iOS and Android SDKs

To set attributes on a user from a mobile device, you will need the latest Airship SDKs to include the new attribute classes.

 Important

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.

iOS

Android

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.

 Important

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 SDKs or our REST API. Examples for setting attributes are included below.

  1. Go to Audience » Attributes and click Create Attribute.
  2. Enter a Name and Attribute ID. Names and IDs must be unique.
    • Name: All characters accepted. 64 characters maximum.
    • Attribute ID: Letters, numbers and underscores only. 128 characters maximum.
       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.

Manage 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.
  • You can search for attributes by name or ID.

Edit a Custom Attribute

 Important

  • Attribute IDs are case-sensitive.
  • If you edit an attribute ID, also update your app with its new value, and vice versa. Changing the attribute ID is effectively the same as creating a new attribute, as the new ID will carry over data stored in the previous ID.

  1. Go to Audience » Attributes.
  2. Click for an attribute.
  3. Edit the attribute name or ID.
  4. Click Save.

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 mobile SDKs or our Channels API.

Set Attributes from the SDK

To set the value for an attribute from the SDK, use the UAAttributeMutations and AttributeEditor classes, for iOS and Android, respectively.

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

Android
UAirship.shared().getChannel().editAttributes()
        .setAttribute("last_product_purchased", "A1234567")
        .removeAttribute("purchase_pending")
        .apply();

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

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

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/(channel_id)/attributes?platform=(platform) endpoint to perform either the set or remove action on an attribute.

 Note

This 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/(channel_id)/attributes?platform=ios HTTP/1.1
Authorization: Basic <App Auth>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

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.

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

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, contains. (less and greater will be available when Number and Date attributes are supported later in this beta.)

Example:

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

Dashboard

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

    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"EN"
Language Countryua_countryApptwo-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"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"Africa/Abidjan"