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.

Tags are generally descriptive terms indicating user preferences or other categorizations, and they 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.

Tags help you track information about your audience. So, in general, 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 clicking, tapping, or using a link
  • Visiting 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" ]
    }
}

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 tags that represent the properties of a device, such as language and time zone settings, OS and browser versions, and notification opt-in status. Device property tags are stored automatically and can be used to target your audience. There are multiple device property tag groups, and they all begin with ua_.

 Note

You cannot modify Device Property tags or tag groups.

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.

While named users don’t have their own “device tags”, Airship makes use of the channels associated with a named user when you take advantage of features that rely on device tags.

See reference: Device Property Tags.

Custom Tag Groups

In general, we suggest that you use custom tag groups so that it’s easier to take advantage of tags at both the channel and named user levels.

You can can create up to 100 tag groups for the data you want to track, e.g., purchase history or CRM data. You must create tag groups in the dashboard before you can use the tag group to apply tags to your audience. See: Manage Tag Groups.

After you create your tag groups, you can apply tags in these groups to channels and named users, and target tags within each group. There is no explicit call to create a tag. Any method that applies tags will also create a tag if it doesn’t already exist.

When you set tags on a channel or named user, you specify the group you want the tag to belong to.

Similarly, when you target an audience, you specify the tag group and tag that you want to target.

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

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.

 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 do not exist at the named user level.

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

{
   "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"
      }
   }
}

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.

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
UAirship.channel().addTag("a_tag")

// Remove a tag
UAirship.channel().removeTag("a_tag")

// Update registration
UAirship.channel().updateRegistration()

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" ]
}

Setting Tags via User Actions

You can set and/or remove tags on your audience when they interact with your messages. 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.

Configure tag actions in the dashboard:

  • For the Message, A/B Test, Automation, and Journey composers, click Set a tag in the Content step. See: Composer Overview: Set a Tag.
  • For the In-App Automation composer, you can set and/or remove tags when a user presses a button in the message. See: Button Actions: Set a Tag.

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": [
        "android"
    ]
}

Creating Segments Using Tags

Create audience SegmentsReusable audience selection criteria. You can use segments when targeting an audience instead of recreating your audience selections every time you send a message. based on tags and tag groups you applied to channels:

Targeting Users Using Tags

In the dashboard, select Target Specific Users in the Audience step of the Message, A/B Test, and In-App Automation composers:

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

Retargeting segments are accessed from a parent message’s message report. Follow the steps in the audience retargeting tutorial.

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"
   }
}

Triggering Automation Based on Tag Changes

Tag changes can be used as triggers for automation and journeys, so you can use tag actions to trigger follow-up messages. See: Configure Triggers: Tag Change.