Tags and Named Users

Overview

Use tags and named users to organize channels and effectively target specific audiences:

  • Map all of an individual user's channels (mobile device, web browser, email address, etc.) to a single Named User.
  • Create nested groupings of Tags into — you guessed it — Tag Groups.
  • Associate tag groups with individual channels and/or named users.

Example

Scenario: Your CRM database indicated that 2,000 of your users are interested in partner offers, and you want to be able to message only those users.

Solution:

  1. Create a tag group called crm.
  2. Tag those 2,000 named users or channels, placing the partner tag in the crm tag group.
  3. Target your partner audience by sending offer messages to users who have the 'partner' in the 'crm' tag group.

Best Practices

  • All your users' channels should be associated to a named user.
  • Tags should be applied via tag groups.
  • Tag groups should be associated with named users in order to reach all of a user's channels.

In most cases, you should place tags into tag groups before associating them with channels.

While tags can be associated with channels without using a tag group, using either the SDK or the tags array when registering a channel, these tags can be overwritten by client-side operations.

Also, tags that do not belong to a tag group cannot be associated with named users, preventing you from taking advantage of orchestration and other advanced features.

Key Terms

Channel
A channel is an individual addressable entity that you can notify via Urban Airship.
Named Users
Named users are groups of channels that represent individual users.
Tags
Tags are metadata associated with a device or user to track user attributes or behavior. Tags are used to group and target your audience. Tags themselves should normally belong to a tag group.
Tag Groups
Tag groups are arrays of tags that you can associate with both channels and named users.

Tags and Tag Groups

Tags belong to tag groups. Tag groups are arrays of tags that you can associate with both channels and named users; they appear in a channel's tag_groups object, or a named user's tags object.

Note

The default Primary Device Tags group is an exception. See Tag Group Types below for more information about primary device tags and why you should avoid using this group.

You must create tag groups to apply tags to channels and named users through the API. While tags can be created via the SDK, API, or dashboard, tag groups are created from the dashboard only.

When you apply tags to a channel or named user, you specify the group you want the tag to belong to and the tag(s) you want to apply to your audience. If your tag does not already exist, it will be created. When you target an audience, you do the same thing: specify the tag group containing the tag you want to target, as well as the tag within that group that you ultimately want to target.

Note

A tag group can be related to an external source of data, however there is no actual connection between the Tag Group and your external 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 users are not automatically tagged to reflect that 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.

Tag Group Types

There are three major types of tag groups:

  1. Primary Device Tags

    By default, tags set client-side through the SDK based on user interaction with your app belong to the Primary Device Tags tag group. This group is represented by a channel's tags array. Primary device tags cannot be applied to named users, cannot be applied through the API, and can be overwritten by client-side operations. Therefore, it is strongly recommended that you use Custom Tag Groups instead, so you can take advantage of Urban Airship's advanced targeting and analytic features.

  2. Device Property Tags

    The Urban Airship SDK automatically collects data from your user’s devices, represented as Device Properties in the dashboard and stored in tag groups beginning with ua_. These groups consist of:

    • Data we collect from your app’s knowledge of the device and OS.
    • Push, Location, and Background Processing opt-in status of your app.
      Note

      You cannot modify Device Property tags or tag groups.

  3. Custom Tag Groups:

    The preferred method for applying tags. You can create custom tag groups for whatever data intend to track, e.g., purchase history or CRM data. You can then apply these groups, and any tags you associate with the group, to channels and/or named users via the SDK, API, or dashboard. You may create up to 100 custom tag groups.

Tag Example

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. The following example targets channels with the tag blue in the group fish_colors:

{
   "audience": {
      "tag": "blue",
      "group": "fish_colors"
   }
}

If you do not specify a group, Urban Airship will use the Primary Device Tags group, represented by the tags array for a channel.

Use Cases

  • Associate with External Data
    Tag groups help you target users based on data stored in a separate database, i.e., inaccessible from the app or browser using the Urban Airship SDK. Examples include:

    • Purchase history
    • Unused credit on account
    • VIP user status
      Note

      If your app requires a user to authenticate with a login and password, once authenticated, you can begin to associate external data with the user's device for targeting using the Named Users API.

  • Set User Preferences
    Apply tags based on stated user preferences. Many apps use preference panels where users can state their interest in certain alert topics such as:

    • School closure alerts
    • Entertainment stories
    • Dodgers score updates
  • Observe In-App Behaviors
    Apply tags based on user behaviors in your app:

    • User browsed a particular piece of app or web content.
    • User logs in frequently/power user.
  • Set Tags for User Actions
    Set tags based on user interaction with notifications via Message Actions.

  • Create Audience Segments using Tags
    Use the Segments Builder to create audience segments based on tags and tag groups you have applied to channels.

Named Users

Named users are groups of channels that represent a single user. A single user may access your service via web, smartphone, email, etc. — all represented as separate channels in Urban Airship. You can map those channels to a single named user that you can target in your message audience.

Named users can be used to send messages, manage tags, and query current status, without needing to store a mapping of users to channel IDs. There is no explicit call to create a named user. A named user record is created in our system the first time we encounter a particular named user ID, usually from a call to the association endpoint.

Named users support Orchestration for more advanced audience targeting and message optimization across channels associated with named users, and can help you better understand your audience as more than individual messaging channels.

Named users are a key integration point if you are targeting users on multiple channels, especially if you are able to map Urban Airship channels to your internal customer identifiers. We strongly recommend using named users in order to take advantage or our Orchestration feature set.

How Named Users Work

A channel ID is a associated with a single mobile device, web browser, email address, open channel, or phone number. A named user can be used to refer to a group of devices associated with an end user.

There are three components to a Named User object:

{
   "named_user_id": "user-id-90210",
   "tags": {
      "fish_colors": [ "..." ]
   },
   "channels": [ "..." ]
}
  • named_user_id is a unique identifier for the Named User. This string serves as the user identifier that links your CRM data with Urban Airship. Choose a simple yet secure identifier, such as a hash of a user's email address.
  • tags contains tag_group arrays that you want to associate with the named user.
  • channels is an array of channel objects associated with the Named User. You can associate up to 50 channels with a single Named User.
Important

A Named User can have multiple associated channels, but a channel can only be associated with one named user.

While it may be tempting to think of Named Users as an interface for interacting with a collection of channels, it's more accurate to think of a Named User as a single, unified object. Once a channel is removed from a Named User, it is disassociated from all of the tags and other data that were applied to the channel via the Named Users tag endpoint. For example, if channel B is associated to Named User X, and a request is received to associate channel B with Named User Y,

  1. channel B will be disassociated from Named User X and associated to named user Y.

    AND

  2. When channel B is disassociated from Named User X, all of the tags set on channel B while it was a member of Named User X are immediately removed.
Warning

Tags added to a channel via a call to the Named Users tag endpoint will not be listed when doing a channel lookup or listing. To see these Named User tags, you must use the Named Users lookup and listingendpoint.

Best Practices

The best time to associate named users is on login and registration within your app. The best time to disassociate named users is on logout, uninstall, etc.

You should setup automatic disassociation calls to avoid running into maximum number of channels per named user (50). You can easily reach this limit if there are multiple developers testing on multiple devices.

Use Cases

  • Connect store loyalty card and point of sale data to in-app coupon experiences based on loyalty status and purchases.

  • Re-message app users on other channels.

  • Send flight status alerts to individual travelers.

  • Reduce costs and over-messaging by sending to a user’s preferred channel, based on the user’s interests.

  • Data collection mechanism for mapping users within your backend system for better retargeting, such as subscription-based modeling.
Important

Named user is a requirement for tying your backend database to Urban Airship data. Implementing named users also enables deeper functionality in other areas of the Urban Airship platform, such as Insight and Connect, providing much higher-resolution data down to the individual user rather than just the device.

How To

Implement Named Users

Named users require SDK 6.0 or later. You can associate channels to named users either automatically when users log in, or manually.

Below are some native examples to help you set Named Users client-side.

Example: iOS Named User

UAirship.namedUser().identifier = "NamedUserID"

Example: Android Named User

UAirship.shared().getNamedUser().setId("NamedUserID");

Your implementation of Named Users may vary by platform. For more information, see the relevant Platform documentation.

For information about pushing to, setting tags on, and querying named users, see: API: Named Users.

Create Tag Groups

  1. Navigate to Settings » APIs & Integrations » Tag Groups.
  2. Follow the steps in Settings: Create a Tag Group.
Note

Tag groups should be named to reflect the source of data that produced the 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 contained within a crm tag group on those users' devices.

Set Tags

You do not need to perform separate actions to add a tag to a tag group and apply tags to an audience.

Any method that applies tags to channels or named users will also create tags and add them to groups if those tags did not already exist within the group.

SDK

Set tags via the SDK:

API

Add tags to tag groups and apply tags to your audience using these API endpoints:

See also: Create and push to a tag group: Add Tags to the Tag Group.

Dashboard

When creating messages by using a dashboard workflow you have the option to set a tag. See: Workflow Overview: Set a Tag.

Target Specific Users

API

Use the audience selector to target tag groups, named users, or named users bearing different tags and tag groups.

Dashboard

When selecting your audience in the Message, A/B Test, and In-App Automation workflows you have the option to Target Specific Users.

Create Segments

Create audience segments based on tags and tag groups you applied to channels.