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:

1. Create a tag group.
2. Add tags to the tag group.
3. 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.

Push to a Tag Group

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