Setting and removing tags

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 tagsA tag set without specifying a custom tag group. Belongs to the device tag group and applies to a channel only, not a named user. or device propertyInformation about a channel, such as language and time zone settings, OS and browser versions, and notification opt-in status. Device properties apply to a channel only, not a named user. Values come from the user’s device when an SDK is present, or are set via the API for channels without one. Each property is automatically made available as an attribute, a tag, or both for audience segmentation. 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.

For details on how tags are stored under contact-level and channel-level segmentation, see 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.
2. 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.

3. (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 secretAuthenticates API requests for an Airship project when paired with the app key. It is intended to be embedded in distributed applications and is limited to the API endpoints required for SDK operations. can modify tags on their device to gain access to messages meant for other audiences or opt themselves out of ones intended for them.

4. 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

Bulk add or remove the same tags for the users listed in a CSV of channelA device or address registered with Airship to receive messages, such as a mobile app, web browser, email address, or SMS number. It stores opt-in status, device-specific information, and metadata used for targeting. Each channel has a unique channel ID. IDs, named userA contact identified with an ID you provide, such as a customer ID from your CRM. Associating channels with that ID maps multiple devices and channels to one individual. Each named user has a unique named user ID. IDs, email addresses, or MSISDNs. You cannot mix identifier types. When using email or SMS identifiers, Airship registers new channels for addresses or MSISDN/sender combinations that are new to your project.

Custom tag groups must exist in your project before you upload. See Create custom tag groups. After you upload the file in the dashboard, select which tags to add or remove.

Prepare your file

Your CSV lists the audience only. Do not include tags. You can download a sample formatted CSV in the dashboard. Go to Audience, then Tags, then Set tags, and select Download sample CSV.

Format a CSV file using the following requirements:

Add opt-in status fields with date-time values for email and SMS so you can send to newly created channels:

• SMS: ua_opted_in
• Email:
  • ua_commercial_opted_in or ua_commercial_opted_out — Opted-in and opted-out dates are mutually exclusive. Providing both in the same row is invalid.
  • ua_transactional_opted_in or ua_transactional_opted_out — Follow the same mutually exclusive rule as commercial dates.
  • ua_open_tracking_opted_in or ua_open_tracking_opted_out — By default, new channels are opted in to open and click tracking. Opt out by setting an opted-out date. Opt back in with an opted-in date that is newer than the opted-out date. Providing both dates in the same row is invalid.
  • ua_click_tracking_opted_in or ua_click_tracking_opted_out — Follow the same rules as open tracking.

To set the suppression state for email channels, use the ua_email_suppression_state field with value BOUNCE, SPAM_COMPLAINT, COMMERCIAL_SPAM_COMPLAINT, or IMPORTED.

To set the time zone for email channels, use the timezone field with an IANA time zone database value, for example, America/Los_Angeles.

channel_id
<id1>
<id2>
<id3>

msisdn,sms_sender,ua_opted_in
15558675309,12345,2020-05-05T10:34:22
15559867543,12345,2020-05-05T12:03:45

Upload your file

Complete these steps in the dashboard:

1. Go to Audience, then Tags, then Set tags.
2. Select Choose file and select your CSV.
3. 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.
4. 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

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

• Creation date
• New version uploaded

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 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.

For code samples and platform-specific details, see the tags topic 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
• Channel Tags
• Email Tags
• Open Identifiers Tags

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.

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 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:

^{1. You must use the drag-and-drop option in the Interactive editor to create the content.}

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.

For push, web push, in-app messages, Message Center, and landing pages, see Actions and Buttons. For the API, specify tag actions in the actions object of the payload for the Send a push endpoint, either at the notification level or per-button under interactive.button_actions.

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.
• Shortened link taps — Add tag actions to Airship-shortened links in your SMS and MMS content. See 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.

Verifying tags on a user

To confirm which tags are set on an individual channel or named user, use the Contact Management tool.