# Tags 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 [Channel](https://www.airship.com/docs/reference/glossary/#channel_dev) and [Named User](https://www.airship.com/docs/reference/glossary/#named_user) 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:** ```json { "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 {#tag-groups} All tags are categorized in *tag groups*. There are three types: | Tag group type | Tag group name | Creator | Tag source | Editing | | --- | --- | --- | --- | --- | | Device property tags| Various | Airship | SDK or API | You cannot edit the tags or the tag group names. | | Custom | Various | You | SDK or manually set | You can manage all the tags and tag group names. Maximum 100 custom tag groups. | | Primary device tags | `device` | Airship | SDK or manually set | You 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. > **Note:** You cannot modify device property tags or tag groups. See reference: [Device Property Tags](https://www.airship.com/docs/reference/data-collection/device-properties/#device-property-tags). ### Primary device tags {#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. > **Important:** 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. > **Note:** Primary device tags are associated with channel IDs only, not named users. **Channel with device tags:** ```http 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": [ "tag1", "tag2" ], "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 {#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. > **Note:** 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 their data source for 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 > **Warning:** 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*. 1. Click **Create 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`. > **Note:** Airship reserves tag groups prefixed with `ua_`. Any tag groups you might create with that prefix will not function. 1. (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. > **Note:** 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. 1. Click **Create tag group**. #### 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. 1. Click for a tag group. 1. Check or uncheck the box for *Enable this Tag Group*, or edit the name or description. 1. Click **Update tag group**. ## 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 [Action](https://www.airship.com/docs/reference/glossary/#action). 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. > **Note:** 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: | Content | Message action | Button press | Image press | | --- | :---: | :---: | :---: | | [Push Notification](https://www.airship.com/docs/reference/glossary/#push_notification) | ✓ | ✓ | | | [Web Push Notification](https://www.airship.com/docs/reference/glossary/#web_push_notification) | ✓ | ✓ | | | [In-App Message (standard)](https://www.airship.com/docs/reference/glossary/#in_app_message) | ✓ | ✓ | | | [Message Center](https://www.airship.com/docs/reference/glossary/#message_center) | | ✓ | ✓ | | [Landing page](https://www.airship.com/docs/guides/features/messaging/landing-pages/) | | ✓ | ✓ | | [In-App Automation](https://www.airship.com/docs/reference/glossary/#iaa) | | ✓ | ✓1 | | [Scene](https://www.airship.com/docs/reference/glossary/#scene) | | ✓ | | 1. Must use WYSIWYG editor to create the content. --- Using the API, specify tag actions in the `audience` object. **Push with a tag action** ```http POST /api/push HTTP/1.1 Authorization: Basic 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": [ "android" ] } ``` ### Content display You can add and/or remove tags when a [Scene](https://www.airship.com/docs/reference/glossary/#scene) or [Rich Page](https://www.airship.com/docs/reference/glossary/#rich_page) is displayed. For rich pages, you must use Visual editor to create the content and configure an *Onload* field. ### File upload [AXP](https://www.airship.com/docs/reference/feature-packages/) Bulk add and/or remove tags in custom tag groups by uploading a user list in a CSV file. 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. If you are assigning tags for custom tag groups, they must already exist in your project. See [Creating custom tag groups](#creating-custom-tag-groups) above. 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 » Tags » Set tags*. You can click **Download sample CSV** to see a formatted file. 1. Click **Choose file** and select your CSV. 1. 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 select from the search results. 1. 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. #### Retention and deletion

Airship automatically deletes a list and all its versions after 90 days of inactivity. Timestamps used to calculate the 90-day period:

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.

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 will still exist on the channel after list deletion. ### SDK You can use the SDK to set tags on channels as your audience navigates your app and website. See our [SDK](https://www.airship.com/docs/sdk-topics/tags/) documentation for code samples and additional information. ### API 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: * [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) * [Open Identifiers Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifyopenchanneltags) * [Email Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifyemailchanneltags) #### 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** ```http POST /api/push HTTP/1.1 Authorization: Basic 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 You can include Attributes when using the **Target by conditions** and **Target specific users** audience options for messages and experiments. You can also create [Segments](https://www.airship.com/docs/reference/glossary/#segment) instead of having to recreate your audience selections. Both use the same process. Tags can be combined with other segmentation data, such as events and Attributes. For full instructions and usage locations, see [Segments](https://www.airship.com/docs/guides/audience/segmentation/segments/). In the API, target specific users via the `"audience"` object. See [API: Audience Selection](https://www.airship.com/docs/developer/rest-api/ua/schemas/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`: ```json { "audience": { "tag": "blue", "group": "fish_colors" } } ``` ## Creating segments Create [Segments](https://www.airship.com/docs/reference/glossary/#segment) based on tags and tag groups you applied to channels: * [API: Segments](https://www.airship.com/docs/developer/rest-api/ua/operations/segments/) * [Dashboard: Segments](https://www.airship.com/docs/guides/audience/segmentation/segments/) ## Triggering automation and sequences Tag changes can be used as triggers for automation and [Sequences](https://www.airship.com/docs/reference/glossary/#sequence), and you can use tag actions to trigger follow-up messages. You can also use tags as [Conditions](https://www.airship.com/docs/reference/glossary/#conditions_event_option) for both. See: * [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* * [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create/add-messages/#conditions) in *Add Messages to a Sequence*