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

Tags

Tags are labels that can be applied to channels and Named Users to help you organize and target your audience.

Tag Group object

Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Jump to examples ↓

OBJECT PROPERTIES
  • * array[string]

    An array of tags.

Used in:

Examples

A simple tag group that has 2 tags associated with the group tags.

{
  "sports fan": ["Federer fan", "Messi fan"]
}

A simple Airship-specific tag group, associating one tag with the group

{
  "tag_groups": {
      "ua_locale_country": ["US"]
  }
}

An array of Tag Groups for a channel. Channels can have Airship-specific tag groups; Named Users do not have Airship-specific Tag Groups.

{
  "tag_groups": [
      {
        "sports fan": [
            "Federer fan",
            "Messi fan"
        ]
      },
      {
        "music fan": [
            "Beyonce",
            "Muse"
        ]
      },
      {
        "ua_locale_country": [
            "US"
        ]
      },
      {
        "ua_locale_language": [
            "en"
        ]
      }
  ]
}

An array of Tag Groups for a Named User. Named Users do not have Airship-specific tag groups.

{
  "tags": {
      "crm_id": [
        "abc-123-def-456"
      ],
      "loyalty program": [
        "silver-member",
        "ten-plus-years",
        "valued-customer"
      ]
  }
}

Tag List metadata object

Contains all user-specified data when defining a tag list in Airship. Although add, remove, and set are optional, one or more must be present.

OBJECT PROPERTIES
  • add object<Tag Group object>

    Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • description string

    An optional description for the list.

  • extra object

    An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

  • name stringREQUIRED

    The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

  • remove object<Tag Group object>

    Removes the specified tags from the channel.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • set object<Tag Group object>

    Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Used in:

Tag List response object

Contains information (metadata) about the tag list.

Jump to examples ↓

OBJECT PROPERTIES
  • add object<Tag Group object>

    Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • channel_count integer

    A count of resolved channel identifiers for the last uploaded and successfully processed identifier list. This will always be 0 for attribute lists.

  • created string

    The date-time when the list was initially created.

  • description string

    An optional description for the list.

  • error_path string

    If non-empty, indicates that there were errors in the processed CSV file. The value is either an empty string or a URL to download a file describing the errors.

  • extra object

    An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

  • last_updated string

    The date-time when the identifiers of the list were last updated successfully.

  • name stringREQUIRED

    The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

  • remove object<Tag Group object>

    Removes the specified tags from the channel.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • set object<Tag Group object>

    Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • status string

    A string value representing the state of the list.

    • ready — The list was processed successfully and is ready for sending.
    • processing — The list is being processed.
    • failure — There was an error processing the last uploaded list.

    Possible values: ready, processing, failure

Used in:

Examples

Tag list response object

{
  "name" : "ua_tags_foo",
  "description" : "",
  "extra" : { "key": "value" },
  "add":{
    "tag-group-name": [
      "tag-value"
    ],
    "tag-group-name2": [
      "tag-value2a",
      "tag-value2b"
    ]
  },
  "remove": {
    "tag-group-name3": [
      "tag-value"
    ]
  },
  "set": {
    "tag-group-name4": [
      "tag-value"
    ]
  },
  "created" : "2013-08-08T20:41:06",
  "last_updated" : "2014-05-01T18:00:27",
  "channel_count" : 0,
  "mutation_success_count": 1000,
  "mutation_error_count": 10,
  "error_path":  "https://go.urbanairship.com/api/tag-lists/users_a/errors",
  "status" : "ready"
}