Create and Push To a Tag Group

Tag Groups are arrays 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 and Named Users 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

 Note

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:

Example: Named Users Tags

 Note

This option requires that you have implemented Named Users.

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.

 Note

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

 Note

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