A tag group is an array of tags that you can associate with both channels and named users. Tag groups are used as recipient groups when defining your message audience, either via the dashboard or API. See the Tags guide for more information.
What You’ll Do
In this tutorial, you will:
- Create a tag group.
- Add tags to the tag group.
- Push to the tag group via the API.
Steps
Many of the details involved in creating and using tag groups differ depending on implementation; the example used in this tutorial is of creating and pushing to a tag group for a backend CRM database.
Create a Tag Group
Tag groups are created in the dashboard. Follow the steps in Manage Tag Groups.
Add Tags to the Tag Group
Add tags to tag groups and apply tags to your audience using these API endpoints:
- Named Users Tags (Also see example below)
- Channel Tags [Also see example below)
- Open Identifiers Tags
- Email Tags
Example: Named Users Tags
This option requires that you have implemented Named UsersA customer-provided identifier used for mapping multiple devices and channels to a specific individual. .
Scenario: Your CRM database indicated that 2,000 of your users are interested in partner offers. These users are identified by Named User.
Solution: Tag those 2,000 Named Users by placing the "partner"
tag in the
"crm"
tag group:
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": [
"named_user_1",
"named_user_2",
"named_user_3",
"...",
"named_user_2000"
]
},
"add": {
"crm": [ "partner" ]
}
}
Example: Channel Tags
Scenario: Your CRM database indicated that 2,000 of your users are interested in partner offers. These users are identified by iOS channel.
Solution: Tag those 2,000 iOS channels by placing the "partner"
tag in
the "crm"
tag group:
POST /api/channels/tags/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"ios_channel": [
"b8f9b663-0a3b-cf45-587a-be880946e881",
"f3e277c2-91c6-4494-8ffb-067129b1993f",
"...",
"9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
],
"android_channel": [
"bd36e8c7-5a73-47c0-9716-99fd3d4197d5",
"ca43301c-1893-4d4c-b4ba-8795cff2feab",
"...",
"4ccc05d7-a6ce-4af0-8b15-57bf5ec73d8a"
]
},
"add": {
"crm": [ "partner" ]
}
}
This is very similar to the Named User Tag example above, except the audience now consists of a list of channel IDs rather than a list of Named User IDs.
There are minor differences in tag operations for email and open channels. See the Open Identifers Tags and Email Tags endpoint references for more information.
Push to a Tag Group
You can also select a tag group when defining your audience in the dashboard. See: Target Specific Users and Target Specific Users: In-App Automation.
Continuing the examples above, you can think of
the "crm": [ "partner" ]
map as placing the "partner"
tag in a "crm"
folder on the devices associated with each Named User or iOS channel. Because
tag group relationships are nested, you do not push to users with the
"partner"
tag. Instead, push to those who have the "partner"
tag within the
"crm"
tag group.
Pushing to a tag group is similar to pushing to regular tags. You use the same
/api/push
endpoint with minimal formatting changes.
Example: No Defined Tag Group
A tag group does not have to be specified. Even with the addition of a tag group, this is still a legal operation:
{
"notification": {
"alert": "Hey, new customers!"
},
"device_types": [
"ios",
"android",
"sms",
"web"
],
"audience": {
"tag": "new_customer"
}
}
However, any push you submit without a tag group specifier implicitly adds the
device
group, so the above example is actually being received as the following request:
{
"notification": {
"alert": "Hey, new customers!"
},
"device_types": [
"ios",
"android",
"sms",
"web"
],
"audience": {
"tag": "new_customer",
"group": "device"
}
}
Example: Defined Tag Group
Specify the devices we tagged in the
examples above
by creating an audience consisting of devices tagged with the "partner"
tag
in the "crm"
Tag Group:
{
"notification": {
"alert": "20% off all shoes in select locations!"
},
"device_types": [
"ios",
"android",
"sms",
"web"
],
"audience": {
"tag": "partner",
"group": "crm"
}
}
Operators
Tag groups work with boolean operators and
, or
, and not
. Integrate your
tag groups with complex segments:
{
"notification": {
"alert": "20% off all shoes in select locations!"
},
"device_types": [
"ios",
"android",
"sms",
"web"
],
"audience": {
"and": [
{
"tag": "shoe-buyer",
"group": "device"
},
{
"tag": "partner",
"group": "crm"
}
]
}
}