Tag Groups Walkthrough

This walkthrough will guide you through the process of creating and using your first Tag Group.

Before you attempt to create a Tag Group, you must complete a very important preliminary step:

Step 0: Learn about Tag Groups and the audience management problems they solve by closely reading the Mobile Data Bridge Primer.

It is difficult to adequately emphasize the importance of Step 0. As you will discover, the process of creating and using a Tag Group is simple, assuming you understand what a Tag Group is. Most of the difficulty involved with using Tag Groups is conceptual.

Welcome back! Now that you understand Tag Groups on a conceptual level, you are ready to create one! There are four steps to successfully completing this walkthrough:

  1. Have some non-mobile data (e.g., a CRM database, a business intelligence tool, an eCommerce system, etc.) that you wish use for the purposes of targeting app users.

  2. Create a Tag Group associated with the source of data determined in step one.

  3. Add some tags to your Tag Group.

  4. Push to your Tag Group, using either the UI (see Target Specific Users) or API.

Steps 2 through 4 are covered below. Many of the details involved in creating and using Tag Groups differ from implementation to implementation, so we’ll use a general example throughout this doc: creating and pushing to a Tag Group for a backend CRM database.

Create a Tag Group

  1. Navigate to your app’s Integration Options:

    • Choose your app from the Urban Airship dashboard.

    • Click the gear icon (Settings) dropdown menu, and select APIs & Integrations.

    • Click the Integration Options tab.

    • Scroll to the Tag Groups section.

  2. Follow the steps in Create a Tag Group.

You now have a fully functional Tag Group! That said, it’s a blank slate. A Tag Group doesn’t do you much good until you actually start using it to add tags to users. We cover that process in the next section.

Adding Tags to a Tag Group

Before we proceed with how to use our newly-minted Tag Group, let’s take a brief moment to discuss what a Tag Group isn’t. It’s important to understand that, while a Tag Group is meant to be related to some backend source of data, there is no actual connection between the Tag Group and the database. In other words, if you have a CRM database and an associated crm Tag Group, and your CRM database is collecting data about certain users, your mobile users are not automatically tagged to reflect the additional data.

Instead, this is accomplished by manually tagging mobile users based on relevant data collected by your CRM database, using Tag Groups to reflect the source of the tag and avoid the server/client tagging issue.

When you are ready to start adding tags to a Tag Group, you can choose between two API endpoints:

Named Users Tags

The first option requires you to have implemented Named Users. Assuming you have named users set up, tagging them with Tag Groups is simple.

Scenario: Our CRM database indicated that 2,000 of our users are interested in partner offers.

Solution: We tag those 2,000 users by placing the "partner" tag in the "crm" Tag Group on their devices:

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

That’s all there is to it. 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. If you want to push to users with this tag, you can’t just create a push to the "partner" tag, as Tag Group relationships are nested.

Instead, you must push to those who have a "partner" tag within the "crm" Tag Group. We’ll cover how to do so in Pushing to a Tag Group.

Channel Tags

If you would like to add tags to a Tag Group and you don’t have a Named Users integration, we have updated our other APIs to support the specification of Tag Groups. Let’s again use the scenario of adding a "partner" tag to our "crm" Tag Group, but instead of tagging 2,000 Named Users, we have 2,000 iOS channels we would like to tag:

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 API, except the audience now consists of a list of channel IDs rather than a list of Named User IDs. If we want to reach users with this tag, we cannot just push to the "partner" tag; we have to push to devices that have the "partner" tag within the "crm" Tag Group. Let’s examine how we would do that.

Pushing to a Tag Group

You can push to a Tag Group using either the API or a message composer. This section focuses on sending to Tag Group tags via the API. For information about sending to a Tag Group via a message composer, see Target Specific Users.

Pushing to a Tag Group is similar to pushing to regular tags. The same /api/push endpoint is used, and the formatting changes are minimal. In fact, even with the Mobile Data Bridge update, you can still push to a tag like you would have previously. Consider the following push:

{
   "notification": { "alert": "Hey, new customers!" },
   "device_types": "all",
   "audience": { "tag": "new_customer" }
}

Even with the addition of Tag Groups, this is still a legal operation. The Tag Group does not have to be specified. 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": "all",
   "audience": { "tag": "new_customer", "group": "device"}
}

We can specify the devices we tagged in the previous section 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": "all",
   "audience": { "tag": "partner", "group": "crm" }
}

Tag Groups work with our boolean operators (and, or, and not) in an intuitive way, allowing you to integrate your Tag Groups with complex segments:

{
   "notification": { "alert": "20% off all shoes in select locations!" },
   "device_types": "all",
   "audience": {
      "and": [
         { "tag": "shoe-buyer", "group": "device" },
         { "tag": "partner", "group": "crm" }
      ]
   }
}