Named Users

A named user is an identifier that maps multiple devices and channels to a specific individual.

A single user might engage with your brand via your mobile app or website, SMS, email, etc. — with each of these communication mediums represented as a separate ChannelAn instance representing an entity addressable via the Airship service, e.g., an iOS device, email address, SMS number or web browser. The channel instance or channel object contains all relevant information about a channel, including metadata used for targeting, opt-in status, device-specific information, and, importantly, a unique identifier for the channel, the channel ID. in Airship.

Named users take an identifier that you provide, like a customer ID, and map all Airship channels associated with that individual to the identifier. Implementing named users lets you:

Airship gathers data about how your audience uses your service and notifications across channels, helping you better track and understand real audience behaviors. Named users help Airship’s Performance AnalyticsA customizable marketing intelligence tool that provides access to reports and graphs based on engagement data. and Real-Time Data StreamingA service that delivers engagement events in real time via the Data Streaming API or an Airship partner integration. provide higher-resolution data down to individual users rather than devices.

How Named Users Work

In most cases, implementing named users doesn’t change the way you target your audience. You just assign tags and attributes at the named user level rather than the channel level. When you send a message, you set the tag and attribute conditions you want to use to target your audience, and the device types you want to message. Airship finds associated channels from your named users and sends messages accordingly.

However, Airship can help you coordinate messages across channels assigned to your named users and gather data at the user level rather than the channel level.

 Important

A named user can have up to 50 associated channels, but a channel can only be associated with a single named user.

A Named User object is comprised of:

Example named user object
{
    "named_user": {
        "named_user_id": "cust_23456",
        "tags": {
            "crm_data": [
                "big_spender"
            ],
            "favorite_teams": [
                "Giants",
                "Royals"
            ],
            "alert_categories": [
                "final_score",
                "lead_change"
            ]
        },
        "user_attributes": {
           "ua_country": "US",
           "ua_language": "en",
           "ua_tz": "America/Los_Angeles"
        },
        "attributes": {
            "first_name": "Phil",
            "email_address": "phil@example.com",
            "first_purchase_date": "2018-09-13T05:00:00",
            "average_order_amount": 200
        },
        "channels": [
            {
                "channel_id": "0cc649bb-c54b-4a51-abaa-c5ba94d20e63",
                "device_type": "web",
                "installed": true,
                "opt_in": true,
                "push_address": "https://fcm.googleapis.com/fcm/send/...",
                "device_attributes": {
                    "ua_browser_name": "chrome",
                    "ua_browser_type": "desktop",
                    "ua_country": "US",
                    "ua_local_tz": "America/Los_Angeles",
                    "ua_language": "en",
                    "ua_browser_version": "chrome-83"
                },
                "attributes": {
                    "first_name": "Phil",
                    "email_address": "phil@example.com",
                    "first_purchase_date": "2018-09-13T05:00:00",
                    "average_order_amount": 200
                },
            },
            {
                "channel_id": "29348457-8aad-468c-a038-16509ae3f912",
                "device_type": "android",
                "..."
            }
        ]
    }
}

Associating Channels with Named Users

We provide methods in our SDKs and API for you to associate or disassociate channels with named users. 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.

If you integrate with a CRM, your named user ID should match user IDs in your CRM to facilitate a two-way integration:

  • Forward events from your CRM to trigger messages for named users in Airship.
  • Send events from Airship back into your CRM to track user lifecycle activity.

There is no explicit call to create a named user; Airship automatically creates a named user record when it first encounters a new named user ID, usually from a call to the association endpoint.

Using the SDK to Associate Channels with Named Users

You can set named users on the client side when you enable the named user setting in Settings » APIs & Integrations » Named Users.

This setting enables the SDK to associate channels with named users, but you still need to provide the value that you want to set for a named user identifier. You can associate channels to named users either automatically when users log in, or manually.

iOS (Swift)
UAirship.namedUser().identifier = "NamedUserID"

iOS (Objective-C)
[UAirship namedUser].identifier = @"NamedUserID";

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

Web SDK
UA.then(function(sdk) {
  sdk.channel.namedUser.set(NamedUserID) // associates this channel with a named user
})

 Tip

See our SDK reference for details on setting named users on different platforms:

 Note

You should set up 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.

Using the API to Associate Channels with Named Users

For channels that don’t use the Airship SDK — SMS, email, etc. — or if you decide not to set named users client side, you can associate channels with named users through the Airship API.

The channel information that you associate with a named user can vary by channel. See the Named User Association endpoint for more information about the required fields for different channel types.

Associate an email channel with a named user
POST /api/named_users/associate HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "email_address": "monopoly.man@boardwalk.com",
   "named_user_id": "user-id-1234"
}

Setting Tags On Named Users

When using named users, you should apply your tags to named users rather than channels.

Setting tags at the named user level is a convenient way to associate tags with, and disassociate tags from, a channel. When you add a tag at the named user level, all the channels associated with the named user will also bear that tag. When you remove a channel from a named user, Airship removes tags associated with the named user from that channel.

While you can set tags at the channel level, named users do not inherit tags from their associated channels. Setting tags at the channel level can limit your flexibility when targeting audiences, and can negate the benefits of named users.

Target a named user by tag on their preferred channel
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
    "audience": {
        "AND": [
           {
              "tag": "cool",
              "group": "users_who_are"
           }
           {
              "tag": "user_preferred"
              "group": "ua:orchestration"
           }
        ]
    },
    "notification": {
       "android": {
          "alert": "Android users are cool!"
       },
       "ios": {
          "alert": "Apple users are cool!"
       },
       "sms": {
          "alert": "Texts are the best!"
       }
        
    },
    "device_types": [ "ios", "android", "sms" ]
}

Setting Attributes On Named Users

You can set attributes at both the channel and named user levels.

  • When you set an attribute on a named user, all the channels associated with the named user will also bear that attribute. When you remove a channel from a named user, Airship removes attributes set on the named user from that channel.

  • While you can set attributes on a channel, named users do not inherit these attributes from their associated channels. Setting attributes at the channel level can limit your flexibility when targeting audiences and the benefits of named users.

In general, we recommend that you store attributes at the named user level so you can take advantage of your attributes across any of the channels belonging to your users. Storing attributes at the named user level helps you build and maintain a cohesive relationship with your audience across any of their channels. Setting attributes at the channel level limits the scope of the attribute to that channel.

Using the example favorite_actor attribute contains the value chris, if you store the favorite_actor attribute at the named user level, you can target all contacts who are fans of Chrises over any of their channels. You can keep your audience up to date on Chris-related news, no matter which channels they use to communicate with you.

Use attributes to send to any channel associated with a named user
graph LR A[Named User
with Attributes] B[Attribute Selector] subgraph Audience C[App Message] D[SMS] E[Web Notification] end A --> B B -.-> C B -.-> D B -.-> E

If you store the favorite_actor attribute at the channel level, you can only target fans of Chrises on the specific channels bearing the favorite_actor attribute, limiting the scope of Chris-related communications.

Attributes at the channel level are limited to that channel
graph LR A[App Channel
with Attributes] B[Attribute Selector] subgraph Audience C[App Message] D[SMS] E[Web Push] end A --> B -.-> C

Named users also inherit a few default attributes from the last channel that was associated with them, helping keep your named users up to date with scheduling and locale information. These attributes appear in the user_attributes object.

  • ua_local_tz - The user’s time zone, e.g., “America/Los_Angeles”.
  • ua_country - The user’s ISO 3166 two-character country code, e.g., “US”.
  • ua_language - The user’s ISO 639-1 two-character language code, e.g., “en”.

Pushing to Named Users

In general, you don’t need to select a named user to push to a named user. When working with named users, you should base your strategy around associating tags, attributes, and other information with named users. When you target tags and attributes associated with named users, you can take advantage of Channel CoordinationA group of strategies you can use to target users where they are most likely to receive your message. features without having to make challenging distinctions between channels and named users.

If you need to send directly to an individual named user — for testing, etc. — you can use the named_user_id selector.

Push to an individual named user
{
   "audience" : {
      "named_user" : "user-id-54320"
   },
   "notification": {
        "alert": "Hi, user-id-54320. What's up?"
   },
   "device_types": [
        "ios",
        "android",
        "sms",
        "web"
    ]
}

Channel Coordination

Channel coordination provides advanced audience targeting options and helps you optimize messages across channels. Named users are a key integration point if you are targeting users on multiple channels, especially if you are able to map Airship channels to your internal customer identifiers.

You must implement named users to take advantage of Channel CoordinationA group of strategies you can use to target users where they are most likely to receive your message. features. Airship automatically assigns tags in the ua:orchestration group to channels associated with each named user. You can then target these tags to take advantage of channel coordination strategies.

Using a tag in the ua:orchestration tag group can help you target named users on the channels that they prefer, helping you maximize engagement. See the Channel Coordination tutorial for more information about available channel coordination strategies.

Message users on their last active channel
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Content-Type: application/json
Accept: application/vnd.urbanairship+json; version=3;

{
    "audience": {
       "AND" [
          {
            "tag": "last_active",
            "group": "ua:orchestration"
          },
          {
             "tag": "cool_users",
             "group": "tag_on_named_users"
          }
       ]
    },
    "notification": {
        "alert": "This is a message to your users on their last-active channel!"
    },
    "device_types": [
        "ios",
        "android",
        "sms",
        "web"
    ]
}