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:
- 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 can have up to 50 associated channels, but a channel can only be associated with a single named user.
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": "[email protected]",
"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": "[email protected]",
"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.
Client-side named user association is enabled by default for all projects created on or after July 12, 2022.
Before disabling client-side named user association, consider your use case. When this setting is disabled, restricting association to server-side calls only, you have the added security of requiring your master secret or token to be verified after each call. While increasing security, you also lose the convenience of having your application automatically associate named users on login. Most apps do not require this additional security. But if your app deals with extremely sensitive data, you may want to disable this setting and associate named users exclusively through the API.
- Go to Settings » Project Configuration and click Manage for Named Users.
- 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.
Associating the channel with a Named User ID will implicitly disassociate the channel from the previously associated Named User ID, if an association existed.
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:
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
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": "[email protected]",
"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.
- Prepare your CSV file using the guidelines in Named User Association CSV Format.
- Go to Audience » Attributes » Upload Named User Data. You can click Download sample CSV file to see a formatted file.
- Click Choose file and select your CSV.
- 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
Attributecontains
the valuechris
, if you store thefavorite_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.
with Attributes] B[Attribute Selector] subgraph Audience C[App Message] D[SMS] E[Web Notification] end A --> B B -.-> C B -.-> D B -.-> E
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 thefavorite_actor
Attribute, limiting the scope of Chris-related communications.
with Attributes] B[Attribute Selector] subgraph Audience C[App Message] D[SMS] E[Web Push] end A --> B -.-> C
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:
Default Attribute | Description | Example |
---|---|---|
ua_local_tz | The user's time zone | America/Los_Angeles |
ua_country | The user's ISO 3166 two-character country code | US |
ua_language | The user's ISO 639-1 two-character language code | 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.
{
"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"
]
}
Kategorien