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.

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

Device property tags

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.

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.

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

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.

Creating custom tag groups

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

     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.

    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.

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.

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

^{1. Must use WYSIWYG editor to create the content.}

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

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

Content display

You can can add and/or remove tags when a SceneA single or multi-screen in-app experience cached on users’ devices and displayed when users meet certain conditions in your app or website, such as viewing a particular screen or when a Custom Event occurs. They can be presented in fullscreen, modal, or embedded format using the default swipe/click mode or as a Story. Scenes can also contain survey questions. 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

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.

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.

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 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 platform documentation for code samples and additional information:

• Mobile
• Web

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
• Channel Tags
• Open Identifiers Tags
• Email Tags

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.

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:

• For the Message and A/B Test composers, see Target Specific Users.
• For the In-App Automation and Scene composers, see Target Specific Users: In-App Experiences.

You can also create a Segment to filter audience members entering 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 audience and continuation. Sequences can be connected to each other and to other messaging components to create continuous user experiences in a Journey.. See Configuring a Sequence trigger.

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:

• API: Segments
• Dashboard: Create reusable audience segments

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 audience and 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 ConditionsChannel-, subscription-, or Segment-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:

• Automation Triggers: Tag Change
  • Automation Triggers: Trigger Options: Conditions
• Sequence Triggers: Tag Change
  • Add Messages to a Sequence: Conditions