Mobile Data Bridge Primer

Mobile Data Bridge enables you to segment your audience based on both mobile and non-mobile data. The data sources are Named Users and Tag Groups, working together to optimize your segmentation and targeting capabilities.

Bridging Mobile and Non-Mobile Data

In the context of our customers’ end/app users, user data must exist as a tag (metadata) in order to function as a targeting mechanism for notifications. This metadata is easily associated with a user’s mobile device by using Urban Airship’s tagging functionality.

Urban Airship customers often segment and target audiences via tags based on data from different sources, i.e.:

  • Preferences set from within the app
  • Server-based data such as purchase history from website

Prior to the release of Tag Groups, customers had to choose one source or the other, because tags set from the app would overwrite tags set from a server and vice versa.

Mobile Data Bridge solves this problem by combining the app-generated and server-generated tags.

Let’s take a closer look at these two types of data.

Mobile Data

We refer to tags that are set from the device as mobile data. The mobile descriptor in this case is meant to distinguish between potential sources of data. These data are typically generated from a user’s interaction with the app. When tags are generated by app activity, the Urban Airship SDK sends the data to Urban Airship’s servers, where it is stored in a database for later use in targeting users and building Segments.

Examples of mobile data include:

  • 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
  • In-App Behaviors:

    • User browsed a particular piece of app content
    • User logs in frequently/power user
  • Actions: Tags may also be set by the device when a user interacts with a notification via our Actions Framework. If you’re not familiar with Urban Airship Actions, have a look at the Actions Release Note from our Spring 2014 release.

Non-Mobile Data

Non-mobile data refers to any data about a user or device that originates from one of your databases, typically a CRM or point-of-sale (POS) system.

If your app requires a user to authenticate with a login and password, once authenticated, you can begin to associate non-mobile data with the user’s device for targeting.

Examples of non-mobile data include:

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

Requirements

The client-side component of Mobile Data Bridge requires SDK 6.0+. All server-side API usage will work out of the box. Mobile Data Bridge supports iOS, Android, and Amazon devices.

Tag Groups

Formally, Tag Groups are configurable namespaces for organizing tags. A simple example of a namespace would be a folder, so Tag Groups can be thought of as folders for tags. Just as the file /folder1/example.txt would not be the same file as /folder2/example.txt, the tag new_customer in Tag Group example_group_1 is not the same tag as new_customer in Tag Group example_group_2.

Let’s start with a concrete example of why you may want to use these namespaces:

Suppose you have a backend database that collects information about certain users, e.g., a loyalty program. Assume this database logs non-mobile data, such as a whether a user has purchased something on a website. Using a Tag Group that is associated with this database, you could send a push to all users that have made a purchase through the website in the past week, offering a discount with their next purchase.

Customers that have attempted the above before the release of Mobile Data Bridge know that this kind of server-side tagging posed serious difficulties. We will review these problems below, and then explain how Tag Groups provide a solution.

Server and Client-Side Tagging: A History Lesson

Aside from providing an easy method for integrating with backend databases, Tag Groups were designed to solve a particularly difficult problem:

As is explained in various parts of our documentation, attempting to set tags via the API while having client-side tags enabled in the SDK would result in a very bad time. Specifically, any tags set with the /api/tags/(tag) endpoint would immediately be cleared by the SDK upon registration.

The old solution to this problem was to completely disable client-side tagging, which was very limiting. Indeed, this issue made it impossible to build segments based on both mobile and non-mobile data. You had to choose one or the other.

To illustrate this point, we’ll look at another example, similar to our last example:

Let’s say you have a loyalty database that gathers information on user activity on your website, and proceeds to attach the tags silver-member, gold-member, and platinum-member to certain users.

Previously, if you wanted to add these tags to the relevant mobile devices, it would mean disabling client-side tagging entirely. But you’re interested in your users’ mobile and non-mobile footprint!

With Tag Groups, you can keep client-side tagging enabled and still create server-side tags. Simply create a Tag Group called loyalty, and set all tags related to your loyalty database within the loyalty tag group. Returning to our folder analogy, rather than creating a silver-member tag, you can think of this as creating a /loyalty/silver-member tag. All tags set client-side live inside a predefined tag group called device, and these tags will not interfere with any of the tags set in your loyalty tag group.

While this example is light on details, hopefully it has given you some intuition as to why we created Tag Groups. Next we will address the particulars of creating and using Tag Groups, and the interplay between Tag Groups and Named Users.

How Do Tag Groups Work?

You should think of your tags as fitting into one of two large buckets:

  • Client-side tags are automatically placed in the Primary Device Tags Tag Group (or device Tag Group, if using the API). The Primary Device Tags group is predefined for you, and it is in some sense the “default” Tag Group. Read more about this here.
  • Server-side tags, or tags that you set via the API, are generally placed in Tag Groups that you create. If you are setting tags via the API, you are most likely doing so because there is an external non-mobile source of data that is feeding you information about users, and you would like to use this information to set tags on on users’ devices. For that reason, Tag Group names 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 a user clicks on an Interested in Partner Offers checkbox, you might add a partner tag contained within a crm Tag Group on that user’s devices.

How Do I Use Tag Groups?

To quickly get up and running with Tag Groups, visit our Tag Groups Walkthrough.

Named Users

Named Users are a system for mapping customer-specified IDs to Channels to support integrations with CRMs or other backend databases. They are the successor to our previous CRM integration tool, Aliases.

Named Users can be used to send messages, manage tags, and query current status, without needing to store a mapping of users to Channels. 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.

Aliases: A History Lesson

Aliases provide a basic framework for integrating CRMs with Urban Airship, but their feature set is minimal. After you identified a user in your app (usually via a login or some similar verification process), you could have the application create an Alias for that user. If a person owned multiple devices with your app, the same Alias would be assigned to each device after login. When you pushed to an Alias, you could hit every device associated with a single user in your system.

This, however, is the extent of the Alias feature set. One of the most problematic limitations with Aliases is the inability to directly set tags on them. If you wanted to emulate the functionality of setting tags on Aliases, you would have to maintain a one-many custom mapping of internal user IDs with device identifiers. All of the data associated with the user IDs could then be attached to the relevant device identifiers. Setting up a complicated mapping system is a substantial task, and maintaining it requires even more work — whenever a user installs, uninstalls, or reinstalls your app on some device, you would have to update the mapping!

How do Named Users Differ from Aliases?

Similar to Aliases, Named Users function as a one-many mapping between a user ID and device channels, meaning one Named User can be associated with multiple channels, but a channel can only be associated with one named user. This mapping models the relationship of a single customer (the Named User) and their many devices (the associated channel IDs).

The Alias tagging difficulties explained in the previous section have been resolved with Named Users. The mapping process occurs automatically, giving you the ability to use non-mobile data to set tags on users without building a complicated backend system. The following table summarizes the major differences between Aliases and Named Users:

Feature Alias Named User
Send rich content and push notifications Yes Yes
Manage tags No Yes
Query current status with lookup and listing No Yes
Composer support No Yes

How Do Named Users Work?

A channel is a associated to a single device, while a Named User can be used to refer to a group of devices. There are three components to a Named User object:

{
   "named_user_id": "user-id-9021",
   "tags": {
      "named_user_tags": [ "..." ]
   },
   "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 is a mapping of <tag_group>: [tag_1,...,tag_n] key-value pairs.
  • channels is an array of channel objects associated to the Named User. You can associate up to 10 channels to a single Named User.

A Named User may have multiple associated channels, however a channel may only be associated to one named user. For example:

If channel B is associated to Named User X, and a request is received to associate channel B to Named User Y, channel B will be disassociated from Named User X and associated to named user Y. 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.

This last point is critical. It’s conceptually tempting to think of Named Users as an interface for interacting with a collection of channels, but it’s more accurate to think of a Named User as a single, unified object. Once a channel is removed from a Named User, all of the tags that were set on that channel via the Named Users tag endpoint are wiped from the device.

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 or listing endpoints.

How Do I Implement Named Users?

In order to start using Named Users, you must upgrade to at least SDK 6.0. If you are currently using Aliases and would like to transition these existing Aliases to Named Users, please see Alias to Named User Upgrade. Once you have completed this preliminary step, what you do next depends on whether you want Named Users to be associated automatically through the app:

  • Enable client-side association: By default, Named Users can only be associated explicitly through the API. Many customers will want Named User association to occur automatically through the app, as soon as a user logs in. If you would like to enable this option, please visit the Settings documentation.
  • Don’t enable: If you prefer to only associate Named Users through the API, no more setup is required!

Once you have chosen whether to enable client-side association, you’re ready to start using Named Users. Visit our API docs for information on pushing to, setting tags on, and querying Named Users. For information about sending to a Named User via a message composer, see Target Specific Users.

Alias to Named User Upgrade

If you are currently using our Alias framework, you will likely benefit from the increased security, functionality, and extensibility of Named Users. The process of transitioning your app to the Named User framework requires three steps:

  1. Upgrade your app with the current SDK, and start associating Named Users on login.
  2. Release the new version of your app.
  3. Contact Customer Support or your TAM to initiate a backfill of Aliases to Named Users.

The first two steps ensure that all new app users will be associated to Named Users. The last step will transition your older customers to Named Users.

Using Tag Groups with Named Users

Both Named Users and Tag Groups can be used on their own. If you just want to associate several Channel IDs to a single Named User ID, that’s doable with the Named Users API. Likewise, if you want to create a simple server tag group, so you can set mobile and non-mobile tags without encountering the dreaded server/client tagging issue.

However, the true power of Mobile Data Bridge lies in using Named Users and Tag Groups together. While the abstract nature of these features may obscure their utility, they were built to simplify the process of integrating outside data sources with Urban Airship. To that point, we have created a step-by-step example that illustrates how to use Named Users and Tag Groups to segment your audience with mobile and non-mobile tags.

Further Reading

For more information on Tag Groups and Named Users, please visit:

FAQ

Q: Do Aliases still work?
A: Yes, Aliases will continue to function. However, we encourage customers to switch over to the vastly improved Named Users framework – the above section will help you through the process.

Q: Are Tag Groups supported in the Segment Builder?
A: Yes.

Q: Can I set tags to custom Tag Groups through the SDK?
A: Not currently. All tags set through the SDK will go into the Primary Device Tags group.

Q: Are security controls available for Tag Groups and Named Users?
A: Yes. Please see the Tag Group and Named Users settings documentation for more details.