# Tags

Tags are metadata attached to channels or named users. Tag groups categorize related tags.

Landing page for the Airship tags directory. Use to answer general questions about what tags are and how they fit into audience management. For details, follow the child pages covering tag concepts (about), setting and removing tags (setting), and targeting with tags (targeting).

<!-- PAGE: About tags, PATH: https://www.airship.com/docs/guides/audience/tags/about/ -->

# About tags

> Use tags to target audiences, trigger automations, filter message delivery, and localize content.
## How tags work

Tags are metadata you attach to a [channel](https://www.airship.com/docs/reference/glossary/#channel_term) or [named user](https://www.airship.com/docs/reference/glossary/#named_user) for audience segmentation. They typically describe a user preference or other categorization, such as `wine_enthusiast` or `weather_alerts_los_angeles`.

Airship evaluates tags by presence or absence, not by value. You can set up to 1,000 tags on a single channel or named user, but large tag counts slow audience evaluation.

Tags are organized into tag groups, which categorize related tags such as an `interests` group for preferences or a `loyalty` group for membership tiers. Every tag belongs to a tag group, and the same tag name in different groups is treated as distinct.

[Set or remove tags](https://www.airship.com/docs/guides/audience/tags/setting/) directly using the SDK or API, or by uploading a CSV in the dashboard. You can also configure messages to set or remove tags based on user interaction. For example, tags can capture actions such as viewing a product page in your app, submitting a preference form on your website, tapping a promotional link in an email, or replying to a text message with a keyword.

For some use cases, another feature is a better fit:

- When you need values you can compare or filter, such as `lifetime_purchase_total` or `last_login_date`, use [attributes](https://www.airship.com/docs/reference/glossary/#attribute).
- When you need to read a user's opt-ins from the SDK, for example to display current subscriptions in your app, use [subscription lists](https://www.airship.com/docs/reference/glossary/#subscription_list). This is because tags can be set from the SDK but not read.

## Using tags with messaging

Tags support the following messaging capabilities:

- **Targeting** — Target audiences for messages, [feature flags](https://www.airship.com/docs/reference/glossary/#feature_flag), [A/B tests](https://www.airship.com/docs/guides/experimentation/a-b-tests/), and [Intelligent Rollouts](https://www.airship.com/docs/guides/experimentation/intelligent-rollouts/) based on tag presence or absence. You can also include tags in [segments](https://www.airship.com/docs/reference/glossary/#segment).
- **Triggering** — Set your [Automations and Sequences](https://www.airship.com/docs/guides/messaging/messages/sequences/about/) to run when a tag is added or removed. You can also set a tag change as a Sequence exit condition.
- **Delivery filtering** — Set delivery conditions on Automations and Sequences by requiring or excluding specific tags.
- **Localization** — Use locale and country tags in [Handlebars](https://www.airship.com/docs/reference/glossary/#handlebars).

Targeting and setting tags can work together in a single message. For example, in a push notification about a new film release, target users with the `likes_movies` tag in the `interests` tag group and set the `tapped_movie_promo` tag in the `engagement` tag group when they tap the message. Later, send a follow-up discount to users with the `tapped_movie_promo` tag.

**Target movie fans by tag and set another tag on those who engage**

```json
{
   "audience": {
      "tag": "likes_movies",
      "group": "interests"
   },
   "notification": {
      "alert": "New movie release this Friday. Get tickets before they sell out.",
      "actions": {
         "tags": [
            {
               "type": "channel",
               "action": "add",
               "group": "engagement",
               "tags": ["tapped_movie_promo"]
            }
         ]
      }
   },
   "device_types": ["ios", "android"]
}
```


## Tag types, data sources, and setup

Tags can come from Airship, the Airship SDKs, and you.

The following table shows the data source, description, and setup required for each tag type:

| Type | Data source | Description | Setup |
| --- | --- | --- | --- |
| **Device property** | Airship SDKs or customer | The Airship SDKs automatically set device property tags on your audience based on device data such as locale, time zone, and OS. For email, SMS, and open channels, you can assign values that do not come from a device. See [Device properties](https://www.airship.com/docs/guides/audience/device-properties/). | None. |
| **Custom** | Customer | You can add your own tags to your project, organized in tag groups you define. For example, you may want to group tags for user interests, loyalty tiers, or CRM data. | Create custom tag groups in your project, then set tags on your audience. |
| **Primary device** | Customer | Any tag you set without specifying a custom tag group is assigned to the `device` tag group. | None. |

> **Warning:** When the app and web SDKs update Airship, all primary device tags are replaced by the data coming from the app or website. Custom tags only change when you add or remove them. Use custom tags for data you need to persist.


### Feature tags

These Airship features have dedicated tags that enable their functionality:

| Feature | Tag group | Valid tags | Setup |
| --- | --- | --- | --- |
| [Predictive Churn](https://www.airship.com/docs/reference/glossary/#predictive_churn) | `ua_churn_prediction` | `high`, `medium`, `low` | Enable the feature in your project settings. |
| [Optimal Send Time](https://www.airship.com/docs/reference/glossary/#optimal_send_time) | `ua_send_time_prediction` | Hour of day (`0`–`23`) | Enable the feature in your project settings. |
| [Channel Coordination](https://www.airship.com/docs/reference/glossary/#channel_coordination) | `ua:orchestration` | `last_active`, `priority_platform`, `user_preferred` | Implement [named users](https://www.airship.com/docs/reference/glossary/#named_user). |
| [Autogroup](https://www.airship.com/docs/reference/glossary/#autogroup) | `autogroup` | A random number from `1` to `100` | [Contact Airship Support](https://support.airship.com/) to enable autogroup for your account. |

## Where tags are stored

A tag stored on a [contact](https://www.airship.com/docs/reference/glossary/#contact) applies across all channels associated with that user, and a tag stored on a channel applies only to that channel. The following table shows where each tag type is stored under each segmentation system:

| Tag type | Contact-level segmentation | Channel-level segmentation |
| --- | --- | --- |
| Custom | Contact | Contact or channel |
| Primary device | Channel | Channel |
| Device property | Channel | Channel |

Under channel-level segmentation, channel tags do not propagate up to the contact, and Airship removes a contact's tags from a channel when you disassociate it.

For the broader audience-data storage model, see [Data storage](https://www.airship.com/docs/guides/audience/your-audience/#data-storage) in *Your audience*. For details on the segmentation systems and how to check your project's setting, see [Channel-level segmentation](https://www.airship.com/docs/guides/audience/segmentation/about/#channel-level-segmentation) in *Segmenting your audience*.


<!-- /PAGE: About tags -->

<!-- PAGE: Setting and removing tags, PATH: https://www.airship.com/docs/guides/audience/tags/setting/ -->

# Setting and removing tags

> Set and remove tags on your audience from your systems or from user behavior in messages.
## Before you set tags

You must create custom tag groups in your project before you can set tags that belong to them. You do not need to create the individual tags in advance, since Airship creates each one the first time you set it.

No setup is required for [primary device tags](https://www.airship.com/docs/reference/glossary/#primary_device_tag) or [device property](https://www.airship.com/docs/reference/glossary/#device_property) tags, which are set automatically by the Airship SDKs.

### Tag names and limits

Tag names are case-sensitive, can contain up to 128 characters, and cannot have leading or trailing whitespace. Do not include personally identifiable information in tag names, and use stable, lowercase names for consistency across your project.

You can set up to 1,000 tags on a single channel or named user. Large tag counts slow audience evaluation, so avoid setting tags you do not use for targeting.

### Named users versus channels

You can set tags on channels and named users, but their inheritance varies:

* **Channels inherit from named users** — All channels associated with a named user also bear the named user's tags. When you remove a channel from a named user, Airship removes the named user's tags from that channel.
* **Named users do not inherit from channels** — Any tag set at the channel level does not propagate to the named user.

For example, setting the `loyalty_gold` tag on named user `user_abc123` applies it to every channel associated with `user_abc123`.

In general, set tags at the named user level when using named users so you can target across any of a user's channels. Setting tags at the channel level limits the tag to that channel and can negate the benefits of named users.

<center>**Tags at the named user level can be used to target any channel associated with a named user:**
</center>
```mermaid
graph LR
A[Named user<br>with tags]
B[Tag Selector]
subgraph Audience
C[App Message]
D[SMS]
E[Web Notification]
end
A --> B
B -.-> C
B -.-> D
B -.-> E
```


For details on how tags are stored under contact-level and channel-level segmentation, see [Where tags are stored](https://www.airship.com/docs/guides/audience/tags/about/#where-tags-are-stored) in *About tags*.

### Create custom tag groups

Create a custom tag group for each source of tag data you want to manage separately, for example a loyalty database or POS system. You can create custom tag groups only in the Airship dashboard, up to 100 per project, and you cannot delete them.

1. Go to **Audience**, then **Tags**, then **Tag Groups**.
1. Select **Create tag group** and complete the fields:
   | Field | Description |
   | --- | ---|
   | **Name** | Enter a friendly name that describes the tag group's data source, for example, "Loyalty database tags." The name appears in the dashboard when searching for tags and tag groups. |
   | **Description** | Add details about the tag group's source and purpose. |
   | **Group Key** | Enter a unique ID used in API calls, using lowercase ASCII characters only and no spaces, for example, `pos-database`. You cannot change this later. |
1. (Optional) Under **Tag security**, enable **Allow these tags to be set only from your server** to increase security by requiring tag read-write operations to be authenticated with your master secret key. You cannot change this later.
   > **Warning:** If you do not enable this setting, an attacker with your app secret can modify tags on their device to gain access to messages meant for other audiences or opt themselves out of ones intended for them.
> 
>    See [Tag & Named User Security](https://www.airship.com/docs/guides/getting-started/developers/app-keys-secrets/#tag--named-user-security) in *App Keys & Secrets: Security*.

1. Select **Create tag group**, and you will return to your list of all tag groups.

In the tag groups list, you can search by name or group key. After creating a tag group, you can edit its name and description, or disable it.

Disabling a tag group hides it and its tags from search in the dashboard and prevents Sequences that reference it from being republished. Tags already set on your audience remain, and you can re-enable the tag group later.

## Set and remove tags from your systems

Push tag data from an external system, such as a CRM, POS, or loyalty database, into Airship.

### CSV upload

[AXP](https://www.airship.com/docs/reference/feature-packages/)

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

Custom tag groups must exist in your project before you upload. See [Create custom tag groups](#create-custom-tag-groups).

1. Prepare your CSV file using the guidelines in [Tags CSV Format](https://www.airship.com/docs/reference/messages/csv-formatting/#tags-format).
1. Go to **Audience**, then **Tags**, then **Set tags**. You can select **Download sample CSV** to see a formatted file.
1. Select **Choose file** and select your CSV.
1. Select **Add** or **Remove**, enter a tag name in the search field, then:
   * If you search for an existing tag, select it from the search results. Search results include all custom tag groups that contain that tag.
   * If you create a new tag, select **Create new tag: [search term]**, enter a custom tag group name in the search field that appears, then select from the search results.
1. Select **Set tags**.

To see upload status and history, go to **Audience**, then **Tags**, then **Upload History**. For **Tags changed**, select the info icon (ⓘ) for the list of tags. When the status is **Processed with errors**, select the download icon (
) to download the error list.

#### Retention and deletion

<p>Airship automatically deletes a list and all its versions after 90 days of inactivity. Timestamps used to calculate the 90-day period:</p>
<ul>
<li>Creation date</li>
<li>New version uploaded</li>
</ul>
<p>The creation date is the initial day one of the 90-day period. Each instance of uploading a new version resets the timestamp to day one.</p>

After deletion, the list is removed from the upload history and is no longer visible in the Airship dashboard or through API calls. Deletion does not affect the project state. For example, if you use a tag list that adds tag A to a channel, tag A still exists on the channel after list deletion.

### SDK

Use the Airship SDKs to set tags as your audience navigates your app or website. Setting tags in custom tag groups requires iOS SDK 20+ and Android SDK 20+.

Setting tags requires the Tags and Attributes flag in Privacy Manager. Setting contact-level tags also requires the Contacts flag. See [SDK data collection](https://www.airship.com/docs/reference/data-collection/sdk-data-collection/).

For code samples and platform-specific details, see the [tags topic](https://www.airship.com/docs/sdk-topics/tags/) in the SDK documentation.

### API

Use the API to set tags server-side. This is common for integrations and for SMS, email, and open channels, which do not have an Airship SDK.

Set tags on your audience using these endpoints:

* [Named Users Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifynamedusertags)
* [Channel Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifychanneltags)
* [Email Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifyemailchanneltags)
* [Open Identifiers Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifyopenchanneltags)

Each endpoint accepts an `audience` object identifying the users, plus tag operations grouped by tag group key. Use `add` and `remove` together to modify a user's existing tags, or use `set` alone to replace all tags in the specified groups. A single request cannot combine `set` with `add` or `remove`.

**Add and remove tags on named users:**

```http
POST /api/named_users/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
      "named_user_id": ["user-1", "user-2"]
   },
   "add": {
      "loyalty": ["gold", "opted_in"]
   },
   "remove": {
      "loyalty": ["silver"]
   }
}
```


## Set and remove tags from user behavior

Configure tags to apply automatically when your audience interacts with your app, your messages, or your SMS content.

### Message display

Set or remove tags when the following message types are displayed to a user:

| Message type | Supported action | Setup |
| --- | --- | --- |
| [Message Center](https://www.airship.com/docs/guides/messaging/messages/content/app/message-center/) | Set or remove | Configure the **Onload** field in the [Visual editor](https://www.airship.com/docs/guides/messaging/editors/visual/). |
| [Landing page](https://www.airship.com/docs/guides/messaging/messages/content/app/landing-pages/) | Set or remove | Configure the **Onload** field in the [Visual editor](https://www.airship.com/docs/guides/messaging/editors/visual/). |
| [Scene](https://www.airship.com/docs/guides/messaging/in-app-experiences/scenes/create/) | Set | Specify a tag when configuring each screen. See [Set a tag](https://www.airship.com/docs/guides/messaging/editors/scenes/screens/#set-a-tag) in *Configuring screens*. |
| [In-App Automation](https://www.airship.com/docs/guides/messaging/in-app-experiences/in-app-automation/create/) | Set | Specify a tag when configuring triggers. See [In-App Experience Triggers](https://www.airship.com/docs/guides/messaging/in-app-experiences/configuration/triggers/). |

### Message interaction

Set or remove tags when your audience interacts with a message. This helps you segment audiences by how they engaged. For example, add a `tapped_promo` tag when a user taps your promo, then re-target that group with a follow-up or compare it to the message's total audience to measure engagement.

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

| Message type | Message action | Button press | Image press |
| --- | :---: | :---: | :---: |
| [Push notification](https://www.airship.com/docs/guides/messaging/messages/content/app/push-notifications/) | ✓ | ✓ |  |
| [Web push notification](https://www.airship.com/docs/guides/messaging/messages/content/web/) | ✓ | ✓ |  |
| [In-app message](https://www.airship.com/docs/guides/messaging/messages/content/app/in-app-messages/) | ✓ | ✓ |  |
| [Message Center](https://www.airship.com/docs/guides/messaging/messages/content/app/message-center/) |  | ✓ | ✓ |
| [Landing page](https://www.airship.com/docs/guides/messaging/messages/content/app/landing-pages/) |  | ✓ | ✓ |
| [Scene](https://www.airship.com/docs/guides/messaging/in-app-experiences/scenes/create/) |  | ✓ | ✓ |
| [In-App Automation](https://www.airship.com/docs/guides/messaging/in-app-experiences/in-app-automation/create/) |  | ✓ | ✓<sup>1</sup> |

<sup>1. You must use the drag-and-drop option in the [Interactive editor](https://www.airship.com/docs/guides/messaging/editors/interactive/actions/) to create the content.</sup>

Setting tags in custom tag groups from a message interaction requires iOS SDK 20+ and Android SDK 20+.

For In-App Automations and Scenes, see [In-app experience actions](https://www.airship.com/docs/guides/messaging/in-app-experiences/configuration/button-actions/).

For push, web push, in-app messages, Message Center, and landing pages, see [Actions](https://www.airship.com/docs/guides/messaging/messages/actions/) and [Buttons](https://www.airship.com/docs/guides/messaging/messages/buttons/). For the API, specify tag actions in the `actions` object of the payload for the [Send a push](https://www.airship.com/docs/developer/rest-api/ua/operations/push/#sendpush) endpoint, either at the notification level or per-button under `interactive.button_actions`.

**Add a tag when a user taps the Yes button:**

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

{
   "audience": "all",
   "notification": {
      "alert": "Interested in our loyalty program?",
      "interactive": {
         "type": "ua_yes_no_foreground",
         "button_actions": {
            "yes": {
               "actions": {
                  "tags": [
                     {
                        "type": "contact",
                        "action": "add",
                        "group": "loyalty",
                        "tags": ["opted_in"]
                     }
                  ]
               }
            }
         }
      }
   },
   "device_types": ["ios", "android"]
}
```


### SMS interaction

Set or remove tags based on SMS interactions:

* **Keyword replies** — Configure tag actions when users reply with a keyword or alias to your sender ID. See [SMS keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/).
* **Shortened link taps** — Add tag actions to Airship-shortened links in your SMS and MMS content. See [SMS link shortening](https://www.airship.com/docs/developer/api-integrations/sms/link-shortening/).
* **Opt-in workflows** — Set tags during opt-in flows, including double opt-in, and on channels that have not yet completed opt-in. See [SMS opt-in and opt-out handling](https://www.airship.com/docs/developer/api-integrations/sms/opt-in-out-handling/).

## Verifying tags on a user

To confirm which tags are set on an individual channel or named user, use the [Contact Management](https://www.airship.com/docs/guides/audience/contact-management/) tool.



<!-- /PAGE: Setting and removing tags -->

<!-- PAGE: Targeting your audience using tags, PATH: https://www.airship.com/docs/guides/audience/tags/targeting/ -->

# Targeting your audience using tags

> Target users with tags and tag groups, and create reusable segments based on tag data.
Airship evaluates tags by presence or absence, not by value. Target users by specifying a tag and the tag group it belongs to.

## Targeting in the dashboard

In messages, [A/B tests](https://www.airship.com/docs/guides/experimentation/a-b-tests/), [feature flags](https://www.airship.com/docs/reference/glossary/#feature_flag), and [Intelligent Rollouts](https://www.airship.com/docs/guides/experimentation/intelligent-rollouts/), select **Target by conditions** and **Target specific users** in the Audience step. You can configure logic that includes or excludes audience members based on whether or not they have specific tags. Instead of recreating the same audience each time, create [segments](https://www.airship.com/docs/reference/glossary/#segment). Configuration in the audience step uses the same interface and process as creating segments.

For full instructions and usage locations, see [Segments](https://www.airship.com/docs/guides/audience/segmentation/segments/) and [Targeting specific users](https://www.airship.com/docs/guides/audience/segmentation/target-specific-users/).

## Targeting using the API

Airship's audience selector accepts tag conditions, so you can target tags in any endpoint that takes an `audience` object, such as [Send a push](https://www.airship.com/docs/developer/rest-api/ua/operations/push/#sendpush). Specify the tag and the tag group it belongs to. The condition matches channels with that tag in that tag group, including channels that inherit from a [named user](https://www.airship.com/docs/reference/glossary/#named_user).

**Target users who like movies**

```json
{
   "audience": {
      "tag": "likes_movies",
      "group": "interests"
   }
}
```


Use Boolean `NOT`, `AND`, and `OR` operators to combine tag conditions or mix tags with other audience criteria. See [Audience Selection](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/) in the Data Formats section of the API reference.

**Target movie or series fans who haven't tapped the promo**

```json
{
   "audience": {
      "AND": [
         {
            "OR": [
               { "tag": "likes_movies", "group": "interests" },
               { "tag": "likes_series", "group": "interests" }
            ]
         },
         { "NOT": { "tag": "tapped_movie_promo", "group": "engagement" } }
      ]
   }
}
```


As in the dashboard, you can save an audience as a reusable segment and reference it by segment ID from any `audience` selector. See [Segments](https://www.airship.com/docs/developer/rest-api/ua/operations/segments/) in the API reference.

## Triggering Automations and Sequences

[Automations and Sequences](https://www.airship.com/docs/guides/messaging/messages/sequences/about/) can act on tags at three points:

* **Trigger** — Start an Automation or Sequence when a tag changes.
* **Condition** — Require a tag to deliver a message.
* **Exit** — Remove users from a Sequence when a tag changes.

### In the dashboard

Configure tag-driven behavior in an Automation or Sequence:

* [Tag Change](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#tag-change) in *Automation and Sequence Triggers*
* [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create-automation/#conditions) in the Setup section of *Create an Automation*, for gating an entire Automation
* [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create/add-messages/#conditions) in *Add Messages to a Sequence*, for gating a single message in a Sequence
* [Exit events](https://www.airship.com/docs/guides/messaging/messages/sequences/create/outcomes/#exit-events) in *Sequence outcomes*, using a tag change as the exit signal

### Using the API

Use the [Create an Automation](https://www.airship.com/docs/developer/rest-api/ua/operations/automation/#createpipeline) endpoint to create tag-driven Automations. Sequences cannot be created via the API.

To trigger on a tag change, include a `tag_added` or `tag_removed` selector in the `immediate_trigger` object. Both selectors take the same shape.

**Trigger an Automation when a tag is added to a custom tag group**

```http
POST /api/pipelines HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "name": "Loyalty welcome",
   "enabled": true,
   "immediate_trigger": {
      "tag_added": {
         "tag": "gold",
         "group": "loyalty"
      }
   },
   "outcome": {
      "push": {
         "audience": "triggered",
         "device_types": ["ios", "android"],
         "notification": {
            "alert": "Welcome to Gold status."
         }
      }
   }
}
```


To gate delivery on a tag, add a `tag` object to the pipeline's `condition` array using the key `tag_name`, not `tag` (which is the key used in triggers). The `group` field is optional and defaults to `device`. The condition is evaluated before the outcome runs, so only users who meet it are messaged. Set `negated: true` to match on absence of a tag.

**Send only to movie fans who haven't tapped the promo**

```http
POST /api/pipelines HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "name": "Movie promo welcome",
   "enabled": true,
   "immediate_trigger": "first_open",
   "condition": [
      {
         "and": [
            { "tag": { "tag_name": "likes_movies", "group": "interests" } },
            { "tag": { "tag_name": "tapped_movie_promo", "group": "engagement", "negated": true } }
         ]
      }
   ],
   "outcome": {
      "push": {
         "audience": "triggered",
         "device_types": ["ios", "android"],
         "notification": {
            "alert": "Check out this week's movie release."
         }
      }
   }
}
```



<!-- /PAGE: Targeting your audience using tags -->