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 channelA device or address registered with Airship to receive messages, such as a mobile app, web browser, email address, or SMS number. It stores opt-in status, device-specific information, and metadata used for targeting. Each channel has a unique 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 for targeting 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 user-level events in real time to your backend or third-party systems using the Data Streaming API. 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. Attributes 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 100 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

Client-side named user association is enabled by default for all projects. This means named user IDs are set for you automatically when a user logs in to your web or mobile app. You have the option to disable it in your project settings.

To change your named user setting:

1. Next to your project name, select the dropdown menu (), then Settings.
2. Under Project settings, select Named Users.
3. 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

By default, the SDK associates named users on the client side or you can handle it manually. With either method, you must provide the value to set for the named user identifier.

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

• Contacts in the SDK developer documentation.
• Named Users in Segmentation for the Web SDK

Using the API

For channels that don’t use the Airship SDK — SMS, email, and open channels — or if you decide not to set named users on the 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 users 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.

Targeting Named Users

Target named users by the tags and attributes you have associated with them. This lets you take advantage of Channel Coordination features without having to make distinctions between channels and named users.

The named user ID is itself a Text attribute. Airship automatically generates ua_named_user_id for each channel associated with a named user. You can target it in segmentA reusable audience group you create by selecting unique or shared user data. conditions or reference it for personalization with HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}}, to complex evaluations of personalization data.. See Named user ID attribute in the Attributes reference.

To send directly to a specific named user:

• Dashboard — Enter the named user ID using the Target specific users or Target by conditions audience options.
• API — 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 CoordinationA group of strategies for targeting users where they are most likely to receive your message. 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 Coordination 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"
    ]
}