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 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.
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" ]
}
}
About 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.
You cannot modify device property tags or tag groups.
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.
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.
Primary device tags are associated with channel IDs only, not named users.
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.
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.
Creating custom tag groups
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.
Go to Audience » Tags » Tag Groups.
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.
(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.
Click Submit.
Managing custom tag groups
You can enable/disable tag groups and edit names and descriptions.
- Go to Audience » Tags » Tag Groups. You can search for tag groups by name or group key.
- Click for a tag group.
- Check or uncheck the box for Enable this Tag Group, or edit the name or description.
- 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.
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:
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
AXPBulk 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.
Prepare your CSV file using the guidelines in Tags CSV Format.
Go to Audience » Tags » Set tags. You can click Download sample CSV to see a formatted file.
Click Choose file and select your CSV.
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.
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:
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:
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, Survey, 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:
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:
Kategorien