Named users

How named users work

A named user is a contactAny user in your project. Contacts are identified as either an anonymous contact or a named user. Airship can set targeting data on these identifiers, which are also used to map devices and channels to a specific user. identified with an ID you provide, such as a customer ID from your CRM. Associating channelsA 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. with that ID maps multiple devices and channels to one individual. Airship does not create named user IDs automatically.

For example, if a customer uses your iOS app, later opts in to web push, and submits their email address in a form, those channels look like separate users until you associate them with the same named user ID.

TagsMetadata that you can associate with a channel or named user for audience segmentation. Generally, a tag is a descriptive term indicating a user preference or other categorization, such as wine_enthusiast or weather_alerts_los_angeles. and 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. set on the named user, such as a loyalty tag or first-name attribute, apply across associated channels and are available for person-level targeting. Named users also help 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. resolve activity to a person across all of their channels.

Association on login and logout

You can use the SDK in your app or website to associate a channel with a named user ID when someone logs in or registers an account, and clear that association when they log out.

For login or registration, what happens depends on whether the ID is new and whether the channel already has a different ID:

• New ID — If the ID is new to your project and the channel does not already have a named user, Airship creates the named user. Tags, attributes, and other contact data set before login stay with that named user.
• ID already exists — If the channel does not already have a named user, but the ID already exists in your project, Airship does not merge the contact’s pre-login data into the existing named user. The SDK reports a conflict so your app can retain any of that data that should carry over.
• Channel has a different ID — If the channel is already associated with a named user, Airship moves the channel to the new one. Contact data that existed only on the previous named user does not move with the channel.

What data stays with the contact versus the channel depends on where it is stored and your project’s segmentation system. See Data storage in Your audience.

For logout, clearing the association differs by method:

• Reset — The SDK resets the contact, which removes the channel from the named user and creates a new anonymous contact with no existing data. Reset is meant for explicit sign-out. Using it at other times can leave you unable to target the channel by its previous contact data.
• API disassociate — An API call removes the channel from the named user only. It does not create a new anonymous contact.

Removing a channel from a named user does not delete the channel. To delete a named user and its associated channels, use the Named users uninstall API.

Using named users with messaging

Named users support the following messaging capabilities:

• Targeting — Send to a specific named user ID, or build audiences from tags and attributes set on the named user. You can also target the Named user ID attribute. See Targeting named users.
• Channel Coordination — Reach a contact on a preferred or last-active channel when they are opted in on more than one. See Channel Coordination.
• Preference Centers — Update subscription preferences at the named user level per channel type. Preference CentersA page where users can manage their opt-in statuses for the subscription lists in your project. Preference Centers are presented within your app or website or as an Airship-hosted web page. require client-side named user association.
• CRM and integrations — Use the same identifiers for named user IDs and CRM or CDP user IDs so you can forward external events to trigger messages in Airship and send Airship events back for user life cycle tracking. See Integrations.

Named user association can start a Sequence, convert or cancel users in a Sequence, and control who receives the first message:

• Trigger — Start a Sequence when an anonymous channel is associated with a named user. See Contact Association in Automation and Sequence triggers.
• Condition — Restrict the first message in a Sequence to anonymous or authenticated contacts. See Add messages to a Sequence.
• Exit — Use named user association as a Sequence exit event. See Exit events in Sequence outcomes.
• Authentication template — Use the Authentication template to encourage login so anonymous channels become named users. Association at login must be implemented. See Authentication Sequence in Sequence templates.

Named user IDs and limits

Named user IDs must be unique. Use an opaque value, not an email address, phone number, or other personally identifiable information. Named user IDs can appear in logs, exports, and analytics. They are case-sensitive, can be up to 128 characters, and must not include leading or trailing whitespace.

A named user can have up to 100 associated channels, and a channel can be associated with only one named user at a time.

Associating channels with named users

You can associate channels with named users manually one at a time in the dashboard, in bulk by uploading a CSV in the dashboard or over SFTP, or programmatically using the SDK or API. Associating a channel with a named user ID also removes it from any previous named user ID.

One at a time

Create named users and associate or disassociate channels one at a time in the dashboard. See Creating a named user and Associating channels with a named user in Contact Management.

CSV upload

Associate 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. IDs, email addresses, or phone numbers with named users by uploading a CSV file in the dashboard or over SFTP. You cannot mix identifier types. If the named user ID is new to your project, Airship creates the named user. When using email or SMS identifiers, Airship registers new channels for addresses or MSISDN/sender combinations that are new to your project.

Prepare your file

Format a CSV file using the following requirements:

Add opt-in status fields with date-time values for email and SMS so you can send to newly created channels:

• SMS: ua_opted_in
• Email:
  • ua_commercial_opted_in or ua_commercial_opted_out — Opted-in and opted-out dates are mutually exclusive. Providing both in the same row is invalid.
  • ua_transactional_opted_in or ua_transactional_opted_out — Follow the same mutually exclusive rule as commercial dates.
  • ua_open_tracking_opted_in or ua_open_tracking_opted_out — By default, new channels are opted in to open and click tracking. Opt out by setting an opted-out date. Opt back in with an opted-in date that is newer than the opted-out date. Providing both dates in the same row is invalid.
  • ua_click_tracking_opted_in or ua_click_tracking_opted_out — Follow the same rules as open tracking.

To set the suppression state for email channels, use the ua_email_suppression_state field with value BOUNCE, SPAM_COMPLAINT, COMMERCIAL_SPAM_COMPLAINT, or IMPORTED.

named_user,channel_id
Joe,<id1>
9834lejrw,<id2>

named_user,email_address,ua_commercial_opted_in
Abby,brandy@example.com,2022-01-01T18:45:30
98er3o34,jake@example.com,2022-01-01T12:45:30

named_user,msisdn,sms_sender,ua_opted_in
Leia,15558675309,12345,2020-05-05T10:34:22
23jw77s,15559867543,12345,2020-05-05T12:03:45

Upload your file

See SFTP upload for CSV files, or complete these steps to upload in the dashboard:

1. Go to Audience, then Attributes, then Upload Named User Data. You can select Download sample CSV file to see a formatted file.
2. Select Choose file and select your CSV.
3. Select Upload.

To view your uploads, go to Audience, then Attributes, then Upload History. See View upload history in Adding attributes to your project.

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 still exists after list deletion.

SDK

Set the named user ID from a device when a user logs in or registers on your app or website. This is referred to as client-side named user association.

You can do this through the SDK by calling the contact identify method. Call identify on login and reset on logout. You always provide the named user ID value. For platform details, see the following:

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

On shared test devices, call reset or otherwise remove the association on logout so you do not hit the 100-channel limit for a named user.

Control client-side named user association

Client-side association is enabled for all projects by default, but you can change the setting.

Follow these steps to change the 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.

API

Use the Named users association endpoint to associate channels with named users through the API when channels do not use the Airship SDK, or when client-side association is disabled.

Make the request from your server. Required fields vary by channel type. If the named user ID is new to your project, Airship creates the named user when you associate a channel with it. If the ID already exists, Airship associates the channel with that 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": "catherine.duke@example.com",
   "named_user_id": "user-id-1234"
}

To remove a channel from a named user, see the Named users disassociation endpoint.

Targeting named users

You still target with tags, attributes, and other audience conditions the same way you do without named users. Set that data on the named user when you can. When you send a message, Airship finds the associated channels and sends to the device types you specify.

The named user ID is also available as the Text attribute ua_named_user_id on each associated channel. You can use 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 — Set the named_user field in the audience.

{
   "audience" : {
      "named_user" : "cust_23456"
   },
   "notification": {
        "alert": "Your order is ready for pickup."
   },
   "device_types": [
        "ios",
        "android",
        "sms",
        "web"
    ]
}

For building audiences from multiple conditions, see Segmenting your audience and Segments.

Named user lookup

Look up a named user to inspect associated channels and data:

• Dashboard — Use the Contact Management tool.
• API — Use the Named user listing or lookup endpoint. The response is a Named user object.

The named user object contains the following fields:

• named_user_id — The named user ID
• tags — Tags assigned to the named user
• attributes — Attributes assigned to the named user
• user_attributes — The time zone, country, and language attributes copied from the last channel associated with the named user
• channels — An array of channel objects associated with the named user