Tags are metadata that you can associate with channels or named users to help you organize and target your audience. Tag groups categorize your tags.

About tags

Tags are descriptive terms indicating user preferences or other categorizations. They are used to track information about your audience and are set at the ChannelAn 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 UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. level. You can also trigger messages based on a tag change.

Generally, you want to set tags on your audience in response to things they do, like:

  • Subscribing to a particular service
  • Checking a box on your website indicating that they like a particular product
  • Engaging with a message from you by following a link
  • Viewing a page in your app

For example, if members of your audience indicate that they like movies, you might assign those users a likes_movies tag in the interests group. You could then target users by interest, sending a specific message to the subset of your users with the likes_movies tag. Users without the tag won’t get your message.

In the API, tags appear in tags and tag_groups objects.

likes_movies example:
   "audience": {
      "tag": "likes_movies",
      "group": "interests"
    "notification": {
        "alert": "Let's go to the movies sometime",
        "actions": {
            "add_tag": ["tapped_the_notification"]
    "device_types": [ "ios", "android" ]

About tag groups

All tags are categorized in tag groups. There are three types:

Tag group typeTag group nameCreatorTag sourceEditing
Device property tagsVariousAirshipSDK or APIYou cannot edit the tags or the tag group names.
CustomVariousYouSDK or manually setYou can manage all the tags and tag group names. Maximum 100 custom tag groups.
Primary device tagsdeviceAirshipSDK or manually setYou cannot edit the tag group name, but you can add and remove tags from device. Any tag set without defining a tag group will default to the device tag group.

Device property tags

Device properties are metadata representing the default attributes and property tags of a device, such as language and time zone settings, OS and browser versions, and notification opt-in status. Device properties are used for audience segmentation. The data used for the tags and attributes is collected automatically from the Airship SDKs, and are updated daily.

There are multiple device property tag groups, and they all begin with ua_.

You generally use device property tags indirectly. For example, locale can determine when a user will receive a localized message, and time zone can determine when a user receives a message scheduled for delivery using local time. Those are both used by Airship when sending a message without selecting the tag in audience segmentation.


You cannot modify device property tags or tag groups.

See reference: Device Property Tags.

Primary device tags

Primary device tags (or just “device tags”) are in a single tag group: device. This tag group contains any tag set without defining a tag group. Typically this means tags set through the SDK based on user interaction with your app. For example, if you send a push that sets a tag on a user after they tap it, then that tag is added to the device tags group. In general, you can set and target these tags on a channel when you do not specify a tag group.


While you can set device tags through the API or dashboard by targeting the device tag group, device tags can be overwritten by the SDK. Therefore it is strongly recommended that you use create and use custom tag groups when setting tags.


Primary device tags are associated with channel IDs only, not named users.

Channel with device tags:
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

   "ok": true,
   "channel": {
      "channel_id": "01234567-890a-bcde-f012-3456789abc0",
      "device_type": "ios",
      "installed": true,
      "opt_in": false,
      "background": true,
      "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
      "created": "2013-08-08T20:41:06",
      "last_registration": "2014-05-01T18:00:27",
      "named_user_id": "some_id_that_maps_to_your_systems",
      "alias": null,
      "tags": [
      "tag_groups": {
         "tag_group_1": ["tag1", "tag2"],
         "tag_group_2": ["tag1", "tag2"]
      "ios": {
         "badge": 0,
         "quiettime": {
            "start": null,
            "end": null
         "tz": "America/Los_Angeles"

Custom tag groups

In general, we suggest that you use custom tag groups for the data you want to track (e.g., purchase history or CRM data) so that it’s easier to take advantage of tags at both the channel and named user levels.

You must create tag groups in the dashboard before you can use the tag group to set tags on your audience. After you create your tag groups, you can start setting tags on channels and named users. Any method that sets tags will also create a tag if it doesn’t already exist. You can also use the tags for audience targeting.


You can manually relate a tag group to an external source of data, however there is no actual connection between the tag group and your external database.

We recommend that you name your tag groups to reflect the source of data that producing tagging information. For example, if you have a CRM database that records when users click an Interested in Partner Offers checkbox, you might add a partner tag in a crm tag group on those users’ devices.

Creating custom tag groups


You cannot delete tag groups, nor can you edit the Group Key field or Allow these tags to be set only from your server security setting. Check that your Group Key and security setting are correct before saving your tag group.

You can create up to 100 custom tag groups.

  1. Go to Audience » Tags » Tag Groups.

  2. Click Add tag group   and enter:

    • Name — A friendly name for the tag group that will help you recognize the tag group in other places. Pick something easily understandable that describes the associated database, e.g., “Loyalty Database Tags.”
    • Description — Additional information about the tag group, describing the source and purpose for the tag group, if necessary.
    • Group Key — The unique ID for the tag group, and how you will reference the tag group in API calls. It is strongly recommended that you exclusively use lowercase ASCII characters. Spaces are not allowed in a group key. Example: pos-database.

      Airship reserves tag groups prefixed with ua_. Any tag groups you might create with that prefix will not function.

  3. (Optional) Enable Allow these tags to be set only from your server. This increases security by requiring tag read-write operations to be authenticated with your master secret key.


    If you do not enable this setting, tags can be read and written from an app using only the application secret, potentially allowing attackers to use your app secret to read or set their own tags. Whether or not your app will benefit from added security depends on the use case. If preventing attackers from reading or setting their own device tags is absolutely critical, enable this setting.

  4. Click Submit.

Managing custom tag groups

You can enable/disable tag groups and edit names and descriptions.

  1. Go to Audience » Tags » Tag Groups. You can search for tag groups by name or group key.
  2. Click   for a tag group.
  3. Check or uncheck the box for Enable this Tag Group, or edit the name or description.
  4. Click Submit.

Setting tags on your audience

You do not need to create tags before you set them. Any method for setting a tag will also create the tag if it doesn’t already exist.

User action

You can set and/or remove tags on your audience when they interact with your push notifications, web push notifications, and in-app messages. This is configured after setting the message ActionA configurable behavior that occurs when a user interacts with your message, e.g., opening a web page. . You can also set and/or remove tags when they press an image or button in your message.

Tag actions are a simple way to track audience engagement. Set tags to group your audience based on their engagement with your messages, determining the best ways to engage with different sets of users. You can also compare a total message audience with the tags changed within an audience to see how well your call to action performed, and determine the percentage of your audience moving through your funnel.


Setting or removing tags when users interact with your message is limited to Primary Device Tags.

You can add or remove tags when the following actions occur:

ContentMessage ActionButton pressImage press
Push NotificationA message that can appear on any screen on a mobile device. Push notifications appear as banners.
Web Push NotificationA message that slides into the top right or bottom left corner of your audience’s web browser (depending on the browser). On a mobile device, web push notifications appear similar to a push notification.
In-App Message (standard)A message that appears inside of your app. You can send in-app messages to your entire app audience, not just users who have opted-in to push notifications.
Message CenterA place in your app where you can display persistent rich messages, including HTML, video, etc. Similar to email, Message Center represents both the medium (the in-app inbox) and the message type (the messages you send to the inbox).
Landing page
In-App AutomationMessages that 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.1
SceneMulti-screen experiences that 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.
SurveyQuestion-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.

1. Must use WYSIWYG editor to create the content.

Using the API, specify tag actions in the audience object.

Push with a tag action
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

    "audience": {
        "tag": "not_it",
    "notification": {
        "alert": "Tag, you're it!",
        "actions": {
            "add_tag": [ "you_are_it" ],
            "remove_tag" [ "not_it" ]
    "device_types": [

Content display

You can can add and/or remove tags when a SceneMulti-screen experiences that 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. or Rich PageA landing page or Message Center message in your app that can include HTML, video, etc. is displayed. For rich pages, you must use Visual editor to create the content and configure an Onload field.

File upload


You can bulk add and/or remove tags in custom tag groups by uploading a CSV file of users. When using email or SMS identifiers in your CSV file, Airship registers new channels for addresses or MSISDN/sender combinations that are new to your project. Additional fields indicate opt-in statuses so that you can send messages to new channels generated from your CSV upload.

  1. Prepare your CSV file using the guidelines in Tags CSV Format.

  2. Go to Audience » Tags » Set tags. You can click Download sample CSV to see a formatted file.

  3. Click Choose file and select your CSV.

  4. Select Add or Remove, enter a tag name in the search field, then:

    • If searching for an existing tag, click to select from the search results. Search for existing tags returns all custom tag groups that contain that tag.
    • If creating a new tag, click Create new tag: [search term], enter a custom tag group name in the search field that appears, then click to to select from the search results.
  5. Click Set tags.

File upload history is in Audience » Tags » Upload History. The latest upload is listed first, with columns for:

  • File name
  • User name — The user who performed the upload in the dashboard
  • Upload date
  • Tags changed — Counts for the number of tags added and removed. Click   for a list of all tags, tag groups, and + (added) or - (removed) indicators.
  • Rows processed
  • Rows skipped
  • Status — Processed, Processed with errors, Processing, or Failed. For status Processed with errors, click   to download the error list.


You can use the SDK to set tags on channels as your audience navigates your app and website.

iOS tag example
// Set tags
UAirship.channel().tags = ["one", "two", "three"]

// Add a tag

// Remove a tag

// Update registration


Use the API to set tags on channels server-side. You might do this with integrations or for your SMS, email, and Open Channels — channels that don’t rely on the Airship SDK.

You can set tags on your audience using these endpoints:

Setting tags on named users

When using named users, you should apply your tags to named users rather than channels.

Setting tags at the named user level is a convenient way to associate tags with, and disassociate tags from, a channel. When you add a tag at the named user level, all the channels associated with the named user will also bear that tag. When you remove a channel from a named user, Airship removes tags associated with the named user from that channel.

While you can set tags at the channel level, named users do not inherit tags from their associated channels. Setting tags at the channel level can limit your flexibility when targeting audiences, and can negate the benefits of named users.

Target a named user by tag on their preferred channel
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

    "audience": {
        "AND": [
              "tag": "cool",
              "group": "users_who_are"
              "tag": "user_preferred"
              "group": "ua:orchestration"
    "notification": {
       "android": {
          "alert": "Android users are cool!"
       "ios": {
          "alert": "Apple users are cool!"
       "sms": {
          "alert": "Texts are the best!"

    "device_types": [ "ios", "android", "sms" ]

Targeting users

In the dashboard, select Target Specific Users in the Audience step of a composer:

In the API, target specific users via the "audience" object. See: API: Audience Selection.

Using the API, when a tag group is assigned to a channel or named user, you target all channels or named users with the same tag and tag group. This example targets channels with the tag blue in the group fish_colors:

   "audience": {
      "tag": "blue",
      "group": "fish_colors"

See also: Selecting your audience.

Creating segments

Create SegmentsA grouping of audience members selected by unique or shared identifiers. Multiple identifiers can be combined within a segment. based on tags and tag groups you applied to channels:

Triggering automation and sequences

Tag changes can be used as triggers for automation and SequencesA series of messages that is initiated by a trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine its continuation. Sequences can be connected to each other and to other messaging components to create continuous user experiences in a Journey. , and you can use tag actions to trigger follow-up messages. You can also use tags as ConditionsTag-, channel-, or subscription-based requirements for members of your audience to receive a message from an automation or sequence. The message is not sent if your conditions are not met. for both. See: