1. Home
  2. /Developer
  3. /REST APIs
  4. /Airship API
  5. /Data Formats
  6. /Attributes

Attributes

Attributes appear on channels and Named Users. You can target an audience using attribute selectors. Available attribute types are Text, Number, Date, and JSON.

Attribute assignment

Jump to examples ↓

OBJECT PROPERTIES
  • attributes arrayREQUIRED

    The attributes that you want to set for, or remove from, your audience. You can have both set and remove actions in the same request.

Used in:

Examples

Attributes assignment

{
  "attributes": [
    {
      "action": "remove",
      "key": "minor_league"
    },
    {
      "action": "set",
      "key": "position",
      "value": "LF"
    }
  ]
}

Custom and predefined Attributes

Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign.

This object enumerates predefined attributes, but you can create your own in the Airship dashboard.

Jump to examples ↓

OBJECT PROPERTIES
  • account_creation string

    The date-time when the user created their account.

  • advertising_id string

    The IDFA associated with a user.

  • age integer

    The user’s age.

  • altitude number

    The altitude associated with a user.

  • birthdate string

    The user’s birthdate.

  • city string

    The city associated with the user.

  • company string

    The company that a user is associated with.

  • country string

    The country associated with the user.

  • email string

    A user’s email address.

  • first_name string

    The first name of a user.

  • full_name string

    A user’s first and last names.

  • gender string

    A user’s gender.

  • home_phone integer

    The user’s home phone number — similar to an SMS channel msisdn.

  • last_name string

    The last name of a user.

  • latitude number

    The latitude associated with a user — maybe their default location.

  • longitude number

    The longitude associated with a user — maybe their default location.

  • loyalty_tier string

    The loyalty program tier that a user is associated with, e.g., gold, platinum, etc.

  • mobile_phone integer

    The user’s mobile phone number — similar to an SMS channel msisdn.

  • region string

    The state, province, principality, etc. associated with the user.

  • title string

    A default attribute. You must enable this attribute in the dashboard before you can assign it.

  • username string

    A user’s username — generally a part of their login information.

  • work_phone integer

    The user’s work phone number — similar to an SMS channel msisdn.

  • zipcode integer

    A user’s zipcode. This is different from the SMS channel ua_ndc attribute, that records user’s area code or phone number prefix.

  • * object
    One of
    • string

Used in:

Examples

Example Attributes object

{
   "device_attributes": {
      "ua_device_os": "10",
      "ua_country": "US",
      "ua_device_model": "SM-G973U",
      "ua_local_tz": "America/Los_Angeles",
      "ua_app_version": "2020-02-01T002322-goat",
      "ua_location_settings": "true",
      "ua_language": "en",
      "ua_sdk_version": "13.1.0",
      "ua_carrier": "Verizon "
   },
   "attributes": {
      "first_name": "Cool",
      "last_name": "Person",
      "birthdate": "1983-03-15T00:00:00",
   }
}

Date Attribute selector

An attribute object with a DATE schema type. Performs absolute date comparisons for ISO-formatted date values or a relative date comparisons given an integer value and precision, e.g., days, months. Use a date attribute to target a channel or Named User based on the date values.

Jump to examples ↓

OBJECT PROPERTIES
  • attribute stringREQUIRED

    The key for the date attribute that you previously defined in the Airship UI, e.g., "birth_date".

  • operator stringREQUIRED

    The operator used to evaluate the attribute expression. The operator that you use with a date attribute will determine which additional properties will be required in the object. See table for required fields.

    OperatorRequired properties
    is_emptyattribute
    beforeattribute, value, precision*
    afterattribute, value, precision*
    rangeattribute, value
    equalsattribute, value, precision**

    * precision is required, but enum values are different than with an equals operator

    ** precision is required, but enum values are different than with a before or after operator

    Date Attribute Operators:

    • is_empty— Evaluates to true if a channel or Named User does not have a value for the attribute.

    • before— Value is one of:

      • String, ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC.

      • Integer, Relative number of units from the current time (i.e., now) into the past. Example: "before": 20 indicates “at least 20 years ago” given a precision of years.

      • String with the value "now", representing the current date-time, i.e., “before now”. When using the now value, no precision is required.

        Note: When using the before operator, precision value must be one of years, months, days, hours, or minutes.

    • after— Values for after behave identically to before, as described above.

    • range— An ISO 8601 time interval. The format consists of an inclusive start and an exclusive end time date separated with a /, e.g., 2019-03-01T13:00:00/2019-05-11T15:30:00. range does not have a precision.

    • equals— allows for selecting specific or non-specific dates as determined by the precision provided in the attribute object.

      Note: When using the equals operator, precision must be one of:

      • day — an integer which represents the day of the month or “now”.
      • month — an integer which represents the month of the year starting with 1 for Jan or “now” which will use the value of the current month.
      • month_day — a string in the format of “mm-dd” which represents a month and day. Ex. 05-04 is May 4th. Value can also be “now”. If today is 2020-03-09, then value will be “03-09”.
      • year_month — a string in the format of “yyyy-mm” which represents a year and month. Ex. 2020-05 is May 2020. Value can also be “now”. If today is 2020-03-09, then value will be “2020-03”.
      • year_month_day — a string in the format of “yyyy-mm-dd” which represents a specific year, month, and day. Ex. 2020-05-04. Value can also be “now”. If today is 2020-03-09, then value will be “2020-03-09”.
      • or value can be “now” which is the current date-time.

    Possible values: is_empty, before, after, range, equals

  • precision string

    The precision, expressed as a timing interval unit, that Airship uses to evaluate a date attribute expression.

    Possible values: years, months, days, hours, minutes, day, month, month_day, year_month, year_month_day

  • relative_to string

    Specifies whether the date is in the future or in the past. If missing, it defaults to past.

    Possible values: future, past

  • value object
    One of

Used in:

Examples

Date Attribute example

{ "audience":
   {
      "attribute": "birth_date",
      "operator": "equals",
      "precision": "month_day",
      "value": "05-04"
   }
}

Add four days to the current date

{ "audience":
   {
      "attribute": "day_of_travel",
      "operator": "equals",
      "value": "4",
      "precision": "days",
      "relative_to": "future"
   }
}

Compound selector using before and after date operators

{
   "audience": {
      "AND": [
            {
               "attribute": "birth_date",
               "operator": "after",
               "value": 55,
               "precision": "years"
            },
            {
               "attribute": "birth_date",
               "operator": "before",
               "value": 40,
               "precision": "years"
            }
      ]
   },
   "device_types": [
      "android"
   ],
   "notification": {
      "alert": "Hello, Generation X!"
   }
}

Audience who purchased jeans

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "contains",
      "value": "jeans"
   }
}

Audience who did not purchase jeans

{ "audience":
   {
      "NOT":{
         "attribute": "item_purchased",
         "operator": "contains",
         "value": "jeans"
      }
   }
}

Audience who did not make any purchase

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "is_empty",
   }
}

Integer value range

{ "audience":
   {
      "AND":[
         {
            "attribute": "size",
            "operator": "greater",
            "value":12
         },
         {
            "attribute": "size",
            "operator": "less",
            "value": 15
         }
      ]
   }
}

Device Attributes

Native attribute properties that Airship gathers automatically assigns to a channel. Varies by channel type. See: Default Attributes.

For segmentation, when using ua_app_version, ua_sdk_version, or ua_device_os, only semantic versioning formatting is accepted, and anything after the third decimal place is excluded, e.g., 12.2.3-alpha is compared as 12.2.3. You can use operators equals, contains, less, greater, is_empty with values in the formats 1, 1.2, 1.2.3.

OBJECT PROPERTIES
  • ua_app_version string

    The app version that the channel uses.

  • ua_browser_name string

    The browser associated with a web channel.

  • ua_browser_type string

    The browser type associated with a web channel.

    Possible values: mobile, desktop

  • ua_browser_version string

    The browser version associated with a web channel.

  • ua_carrier string

    The cellular carrier of the device associated with an app channel.

  • ua_country string

    The 2-letter country code for an app or web channel.

  • ua_country_code string

    The country dialing code derived from the MSISDN associated with an SMS channel.

  • ua_device_model string

    The model of the device associated with an app channel.

  • ua_device_os string

    The operating system of the device associated with an app channel.

  • ua_language string

    The 2-letter language code for an app or web channel.

  • ua_local_tz string

    The time zone that the SDK registers for an app or web channel.

  • ua_location_settings string

    If true, location settings are enabled for an app channel.

    Possible values: true, false

  • ua_ndc string

    The National Destination Code aka area code derived from the MSISDN on an SMS channel.

  • ua_rcs_enabled string

    Rich Communication Services (RCS) capability for an SMS channel. Set to true when an RCS upgrade delivery receipt is received.

    Possible values: true

  • ua_sdk_version string

    The Airship SDK version associated with an app or web channel.

  • ua_subdivision string

    The ISO 3166-2 code derived from the MSISDN on an SMS channel.

Used in:

JSON Attribute selector

An attribute object with a JSON schema type. Performs value comparisons based on the JSON value for an attribute on a channel or Named User.

Jump to examples ↓

OBJECT PROPERTIES
  • attribute stringREQUIRED

    The name of the attribute.

  • where objectREQUIRED

    An object that filters on the JsonPath expression that you provide.

    OBJECT PROPERTIES
    • compare_as string

      Selects the property type for comparison.

      Possible values: text, number, date, boolean

    • operator stringREQUIRED

      The operator used to evaluate the attribute expression. If the JsonPath expression maps to an array, the only available operators are is_empty, not_empty, contains, or not_contains.

      Possible values: equals, contains, not_contains, less, less_eq, greater, greater_eq, range, before, after, is_empty, not_empty

    • precision string

      Used only for date values.

      Possible values: minutes, days, months, years

    • property stringREQUIRED

      The JsonPath expression that will be used to look up the value in a predefined attribute, for example "$.x['store']['book'][0]['title']". This is different from selecting based on primitive string attributes, because the JsonPath expression can map to a single attribute or an array of attributes. See JsonPath  for more information about JsonPath expressions and usage.

    • relative_to string

      Used only for date values.

      Possible values: future, past

    • value object

      The value of the property you are filtering for in the where object. Use compare_as to select the type for comparison. This is required for all operators except is_empty and not_empty.

      One of
      • string

Used in:

Examples

JSON Attribute examples

{
  // Example 1
  "audience":
   {
      "attribute": "books_on_books",
      "where": {
         "property": "$.x.store.book[*].title",
         "operator": "equals",
         "value": "Dracula",
         "compare_as": "text"
      }
   }
}
{
  // Example 2
  "audience":
   {
      "attribute": "oh_look_a_book",
      "where": {
         "property": "$.x['store']['book'][0]['title']",
         "operator": "equals",
         "value": "Dracula",
         "compare_as": "text"
      }
   }
}
{
  // Example 3
  "audience":
   {
      "attribute": "another_one",
      "where": {
         "property": "$.x.store.codes[*].sneakers",
         "operator": "equals",
         "value": 178394549,
         "compare_as": "number"
      }
   }
}
{
  // Example 4
  "audience":
   {
      "attribute": "and_one_more",
      "where": {
         "property": "$.x['store']['codes'][0]['available']",
         "operator": "equals",
         "value": "true",
         "compare_as": "boolean"
      }
   }
}

NPS survey Attributes

Attributes automatically generated by Airship based on data from your NPS surveys.

OBJECT PROPERTIES
  • ua_nps_category string

    A category based on the score a user submits in an NPS survey. Scores of 9 and 10 are categorized as promoter, 7 and 8 are categorized as passive, and 0-6 are detractor.

  • ua_nps_score number

    The score (0-10) a user submits in an NPS (Net Promoter Score) survey.

Number Attribute selector

An attribute object with a NUMBER schema type. Performs value comparisons based on the number value for an attribute on a channel or Named User.

Jump to examples ↓

OBJECT PROPERTIES
  • attribute stringREQUIRED

    The key for the number attribute that you previously defined in the Airship UI, e.g., "lifetime_value".

  • operator stringREQUIRED

    The operator used to evaluate the attribute expression.

    Possible values: equals, contains, less, greater, is_empty

  • value numberREQUIRED

    The value of the number attribute that you are targeting. For example, 15000.

Used in:

Examples

Number Attribute example

{ "audience":
   {
      "attribute": "lifetime_value",
      "operator": "greater",
      "value": 15000
   }
}

Remove Attribute

Remove an existing attribute from the audience.

Jump to examples ↓

OBJECT PROPERTIES
  • action stringREQUIRED

    Indicate that you want to remove an attribute from the audience.

    Possible values: remove

  • key stringREQUIRED

    The attribute ID for the attribute you want to set. JSON attribute key values must be in format <attribute_ID>#<instance_ID>. See JSON Attributes in About Attributes.

  • timestamp string

    The date-time when the attribute changed. If you don’t enter a timestamp, Airship uses the current time.

Used in:

Examples

Remove Attribute

{
  "action": "remove",
  "key": "minor_league"
}

Set Attribute

Add a new attribute, or edit the value of an existing attribute, for the audience.

Jump to examples ↓

OBJECT PROPERTIES
  • action stringREQUIRED

    Indicate that you want to set an attribute on the audience.

    Possible values: set

  • key stringREQUIRED

    The attribute ID for the attribute you want to set. JSON attribute key values must be in format <attribute_ID>#<instance_ID>. See JSON Attributes in About Attributes.

  • timestamp string

    The date-time when the attribute changed. If you don’t enter a timestamp, Airship uses the current time.

  • value objectREQUIRED

    The value that you want to set for an attribute. Accepts numbers and strings for integer/number type attributes, but your string must be convertible to a number or the request will fail. You can also set an object, which must be valid JSON or the request will fail.

    One of
    • string
    • OBJECT PROPERTIES
      • exp number

        The JSON attribute expiration date, set as the number of seconds since the epoch (January 1st, 1970). After expiration, Airship ignores the Attribute where used in segmentation and personalization. If omitted, Airship automatically sets a value of 90 days from the current date and time. The maximum expiry delay for a JSON Attribute is 731 days.

Used in:

Examples

Set Attribute with string value

{
  "action": "set",
  "key": "position",
  "value": "LF"
}

Set JSON Attribute with its required object value

{
  "action": "set",
  "key": "position#instance_42",
  "value": {
    "exp": 1731531110,
    "name": "LeftField",
    "rank": 2,
    "active" true,
    "extras": [
      "rookie",
      "mvp"
    ]
  }
}

Text Attribute selector

An attribute object with a TEXT schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or Named User.

Jump to examples ↓

OBJECT PROPERTIES
  • attribute stringREQUIRED

    The key for the text attribute that you previously defined in the Airship UI, e.g., "item_purchased".

  • operator stringREQUIRED

    The operator used to evaluate the attribute expression.

    Possible values: equals, contains, less, greater, is_empty

  • value stringREQUIRED

    The string you want to match when evaluating the attribute expression, e.g., "jeans".

Used in:

Examples

Text Attribute example

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "contains",
      "value": "jeans"
   }
}