Named users

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:

• Target users on all their opted-in messaging channels.
• Use Channel CoordinationA group of strategies you can use to target users where they are most likely to receive your message. to contact your audience using the channels they prefer.
• Associate your CRM data with named user identifiers in Airship, so you can take advantage of user data outside Airship to message your audience. See Integrations for more information.

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.

A Named User object comprises:

• named_user_id — The unique identifier that you provided to reference a user in your system. Choose a simple yet secure identifier, such as a user’s internal customer identifier.
• tags — Tags that you have assigned to the named user. Tags set at the named user level apply to associated channels. Tags on a named user are organized within tag groups.
• attributes — A group of AttributesMetadata used for audience segmentation and personalization. They extend the concept of Tags by adding comparison operators and values to determine whether or not to target a user, helping you better evaluate your audience. assigned to the named user.
• user_attributes — A special set of attributes used for localization and scheduling. These attributes (timezone, country, language) are copied from the last channel associated with the named user.
• channels — An array of channel objects associated with the named user. A single named user can contain up to 50 channels.

{
    "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",
                "..."
            }
        ]
    }
}

Client-Side Named User Association

By default, named association occurs server-side via the API. A 403 Forbidden response is returned if named user association is attempted when client-side association is disabled. In order to associate a named user through the application, you must change the project’s named users security setting to allow named users to be set from devices.

1. Go to Settings » Project Configuration and click Manage for Named Users.
2. Enable or disable Allow named users to be set from devices.

Associating Channels with Named Users

You can associate channels with named users by uploading a list to Airship in the dashboard or using SFTP. We also 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

You can set named users on the client side. See: Client-Side Named User Association. 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.

For details on setting named users on different platforms, see:

• Mobile
• Web

Using the API

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.

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@example.com",
   "named_user_id": "user-id-1234"
}

Using a CSV file

Associate channel IDs, email addresses, or MSISDNs with named users by uploading a list in a CSV file. For email addresses and MSISDNs, additional fields indicate opt-in statuses. Upon upload, Airship:

• Registers channels that are new to your project
• Creates the named user ID if it does not already exist

Follow the steps in the SFTP tutorial or follow the steps below for CSV upload in the Airship dashboard.

1. Prepare your CSV file using the guidelines in Named User Association CSV Format.
2. Go to Audience » Attributes » Upload Named User Data. You can click Download sample CSV file to see a formatted file.
3. Click Choose file and select your CSV.
4. Click Upload.

Your dashboard and SFTP uploads are listed in Audience » Attributes » Upload History. The list also includes Attribute uploads. The latest upload is listed first, with columns for:

• File name
• User name — The user who performed the upload in the dashboard
• Source — Dashboard or SFTP
• Upload date
• Status — Processed, Processed with errors, Processing, or Failed

For status “Processed with errors”, select the download icon () to download a CSV file of the identifiers that failed processing and their error reasons.

Retention and deletion

Airship automatically deletes a list and all its versions after 90 days of inactivity. Timestamps used to calculate the 90-day period:

• Creation date
• New version uploaded

The creation date is the initial day one of the 90-day period. Each instance of uploading a new version resets the timestamp to day one.

The retention period for a Named User association list is the same whether uploaded in the Airship dashboard or using SFTP.

After deletion, the list is removed from the upload history and is no longer visible in the Airship dashboard or through API calls. Deletion does not affect the project state. For example, if you use a Named User Association list that associates Channel ID 01234567-890a-bcde-f012-3456789abc0 with Named User meghan, the association will still exist after list deletion.

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.

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 on Channels and Named Users, however their inheritance of Attributes varies:

• Channels inherit from Named Users — All the Channels associated with a Named User will also bear the Named Users’s Attributes. When you remove a Channel from a Named User, Airship removes Attributes set on the Named User from 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.

• Named Users do not inherit from Channels — Any Attribute set for a Channel will not also be set for an associated Named User.

  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.

In general, we recommend that you store Attributes at the Named User level so you can take advantage of your Attributes across any of your users’ Channels. This helps you build and maintain a cohesive relationship with your audience. Setting Attributes at the Channel level limits the scope of the Attribute to that Channel and can also limit your flexibility when targeting audiences.

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:

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.

{
   "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 for more information about available channel coordination strategies.

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