# Build and Manage Your Audience Learn how users are identified in your Airship project, what data can be assigned to them, and how to turn that data into precise audience segments. # Your audience > Learn how your audience is identified, how users are added to your project, where data comes from, and how to use that data for segmentation, personalization, and more. ## Contacts A Contact is any user in your project. Within the Airship documentation, we use "user" and "Contact" interchangeably. You can think of a Contact as a container that holds all the information about a person who can receive messages from you. This includes their devices, communication preferences, and any data you've collected about them. While a Contact can be associated with multiple devices, such as a user's tablet and phone, a device can only be associated with a single Contact. A Contact can be in one of two states: * **Anonymous Contact** — This is a user who hasn't been identified with a specific identifier from your system. Airship automatically creates an Anonymous Contact when someone first interacts with your app, website, or messaging channels. Anonymous Contacts still allow [Tags](https://www.airship.com/docs/reference/glossary/#tag), [Attributes](https://www.airship.com/docs/reference/glossary/#attributes), [Subscription Lists](https://www.airship.com/docs/reference/glossary/#subscription_list), and channel association. * **Named User** — This is a user who has been identified with an identifier you provide, such as a customer ID or username from your system. This allows you to connect all of a person's devices and channels under one identity. Identifying a Contact as a Named User allows you to modify the Contact through Named User APIs and use the Named User ID for segmentation. Airship can set targeting data on these identifiers, which are also used to map devices and channels to a specific user. When a Contact goes from anonymous to named, the anonymous data automatically carries over to the Named User ID, if the Named User is new. If the Named User already exists, a conflict event is emitted by the SDK, and the app is responsible for migrating anonymous data to the existing Named User. See [Named users](https://www.airship.com/docs/guides/audience/named-users/) for more information, including implementation steps. ## Channels A channel is a specific device or communication method that belongs to a Contact. For example, a Contact might have an iOS device, an Android device, an email address, a phone number for SMS, or a web browser registered for web push. Each of these is a separate channel associated with that Contact. A single Contact can have multiple channels, allowing you to reach the same person through different devices and communication methods. Each channel has a unique [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) that Airship uses to identify and send messages to that specific device or communication method. In another context, "channel" can refer to the communication media supported by the Airship Service: app, web, email, SMS, and Open Channels. ### Projects without Named Users If you are not using Named Users, channels are automatically associated together through the SDK and [Opt-in Forms](https://www.airship.com/docs/reference/glossary/#opt_in_form). For instance, if a user submits their email address in a form in an app Scene, that email channel is added to the same Contact ID as the current app channel. ## Contact sources Users enter your project when they interact with your brand through any of your communication channels. Each of these interactions creates a Contact in your project, even if the person hasn't logged in or provided their name yet. The way users are added depends on which channel they use to connect with you: * **Mobile apps** — When someone installs your iOS or Android app and opens it for the first time, the Airship SDK automatically creates a Contact and registers their device. If they opt in to push notifications, that channel is added to their Contact. * **Web push** — When a visitor to your website clicks to allow push notifications, Airship creates a Contact and registers their web browser as a channel. * **Email** — Users are added when they submit their email address through an [opt-in form](https://www.airship.com/docs/guides/messaging/features/opt-in-forms/) or [Scene](https://www.airship.com/docs/reference/glossary/#scene), when you register them manually, or through other methods. Each email address becomes a channel associated with a Contact. See [Register users](https://www.airship.com/docs/developer/api-integrations/email/getting-started/#register-users) in *Getting Started* for email. * **SMS** — Users are added when they text a keyword to your SMS number, submit their phone number through an opt-in form or Scene, when you register them manually, or through other methods. Each phone number becomes a channel associated with a Contact. See [Register users](https://www.airship.com/docs/developer/api-integrations/sms/getting-started/#register-sms-users) in *Getting Started* for SMS. * **Open Channels** — Users are added when you register them manually for channels like WhatsApp, Facebook Messenger, or other custom messaging platforms. See [Register channels](https://www.airship.com/docs/developer/api-integrations/open/getting-started/#register-a-channel-to-your-open-platform) in *Getting Started* for Open Channels. ## Data sources User data can come from multiple sources: * **Automatic collection** — Airship SDKs automatically gather basic information like device type, operating system, language, timezone, and country. This happens in the background when users interact with your app or website. See [Device properties](https://www.airship.com/docs/reference/data-collection/device-properties/). * **User actions** — When users interact with your messages, make purchases, view content, or complete other activities, Airship records these as [Events](https://www.airship.com/docs/reference/glossary/#events) that become part of their profile. * **Your systems** — You can send data from your CRM, e-commerce platform, or other business systems to Airship via APIs or CSV uploads. This might include customer IDs, purchase history, preferences, or demographic information. * **User input** — Information users provide directly, such as when they fill out forms, answer survey questions in Scenes, or update preferences in a [Preference Center](https://www.airship.com/docs/reference/glossary/#preference_center). * **External integrations** — Data from partner systems through integrations like Segment, Salesforce, or other platforms you've connected to Airship. ## Data storage Contact-level data applies to the user across all their devices and channels. [Attributes](https://www.airship.com/docs/reference/glossary/#attributes), [Tags](https://www.airship.com/docs/reference/glossary/#tag), and [Lifecycle Lists](https://www.airship.com/docs/reference/glossary/#lifecycle_list) are stored at the Contact level. Channel-level data is tied to a specific device or communication method. [Device Properties](https://www.airship.com/docs/reference/glossary/#device_properties), primary device Tags (Tags in the `device` tag group), and default [Events](https://www.airship.com/docs/reference/glossary/#events) are stored at the Channel level. Some data types can be set at either the Contact or Channel level: predefined [Events](https://www.airship.com/docs/reference/glossary/#events), [Custom Events](https://www.airship.com/docs/reference/glossary/#custom_event), [Subscription Lists](https://www.airship.com/docs/reference/glossary/#subscription_list), and [Uploaded (Static) Lists](https://www.airship.com/docs/reference/glossary/#uploaded_list). Events from any channel "roll up" to the Contact. This means that channel-level data is available for segmentation purposes for any Contact. > **Note:** For projects using the channel-level segmentation system, custom Attributes and Tags can be set at either the channel or Contact level. For additional differences between systems, see [Channel-level segmentation](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation) in *Segmenting your audience*. ## Data management You can manage user data in several ways: * **Dashboard** — Upload CSV files to add or update user data in bulk, or use the [Contact Management](https://www.airship.com/docs/guides/audience/contact-management/) tool to view and manage individual users. * **APIs** — Use Airship's REST APIs to programmatically add, update, or remove Tags, Attributes, and other data. This is useful for real-time updates from your systems. * **SDKs** — Your mobile app or website can add or remove data directly using Airship SDK methods. This is ideal for capturing user actions as they happen. * **Integrations** — Connected platforms like Segment or your CRM can automatically sync data to Airship. You can remove data by: * Setting Attributes to empty values or removing Tags * Using the API to explicitly remove specific data points * Resetting a Contact to clear all anonymous data, typically done when a user logs out ## Using audience data User data powers many features in Airship that help you send more relevant, effective messages: **Segmentation** — Divide your audience into groups based on their data. For example, you might create a [Segment](https://www.airship.com/docs/reference/glossary/#segment) of users who have made a purchase in the last 30 days, or users who live in a specific city. You can then send targeted messages to these Segments. You can create Segments based on: * Attributes, such as age, location, or purchase history * Tags, such as "premium_member" or "newsletter_subscriber" * Events, such as "purchased" or "added_to_cart" * Subscription lists * Device properties * Named User IDs See [Segmenting your audience](https://www.airship.com/docs/guides/audience/segmentation/segmentation/). **Personalization** — Customize message content for each individual user. Instead of sending "Hello!" to everyone, you can send "Hello, Sarah!" using the user's first name Attribute. You can personalize: * Message text and subject lines * Product recommendations based on purchase history * Special offers based on loyalty tier * Content based on location, language, or preferences See [About personalization](https://www.airship.com/docs/guides/personalization/about/). **Automation** — Trigger messages automatically based on user behavior or data changes. For example, send a welcome message when someone first opens your app, or a re-engagement message if they haven't visited in 30 days. See [Scenes](https://www.airship.com/docs/guides/features/messaging/scenes/scenes/), [In-App Automation](https://www.airship.com/docs/guides/features/messaging/in-app-automation/), and [About Automations and Sequences](https://www.airship.com/docs/guides/messaging/messages/sequences/about/). **Channel Coordination** — When you have Named Users with multiple channels, Airship can help you choose the best channel to reach each person. For example, you might prefer to send messages to the channel they used most recently, or let users choose their preferred channel. See [Channel Coordination](https://www.airship.com/docs/guides/features/orchestration-experimentation/channel-coordination/). **Analytics and insights** — Use user data to understand your audience better. See which segments are most engaged, which personalization strategies work best, and how user behavior changes over time. See [Reports & Analytics](https://www.airship.com/docs/guides/reports/). **Advanced features** — User data also powers these advanced capabilities: * [Predictive Analytics](https://www.airship.com/docs/guides/features/intelligence-ai/predictive/) * [Audience Pulse](https://www.airship.com/docs/reference/glossary/#audience_pulse) * [Journeys](https://www.airship.com/docs/reference/glossary/#journey) * [Experimentation](https://www.airship.com/docs/guides/experimentation/) The more complete and accurate your user data, the more effectively you can use these features to create meaningful, relevant experiences for your audience. # Contact Management > Search, view, and manage contacts. You can use the contact management tool to view details about specific contacts and remove channels and contacts from your Airship records. If on an [AXP](https://www.airship.com/docs/reference/feature-packages/) plan, you can also create [Named Users](https://www.airship.com/docs/reference/glossary/#named_user) and add/remove [Channels](https://www.airship.com/docs/reference/glossary/#channel_dev) to/from a Named User. For SDK methods for managing Named Users, see [Contacts](https://www.airship.com/docs/sdk-topics/contacts/) in our developer documentation. ## Contact lookup You can look up a contact using these identifiers: * [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) * [Named User](https://www.airship.com/docs/reference/glossary/#named_user) — Case-sensitive * [Device Token](https://www.airship.com/docs/reference/glossary/#device_token) * Email address * Phone number — Can include a combination of spaces, dashes, and braces around the area code, for example: `18001234567`, `1 800 123 4567`, and `1 (800) 123-4567` ### Looking up a contact To look up a contact: 1. Go to **Audience**, then **Contact Management**. 1. Enter an identifier and select **Look up**. Lookup results list for each identifier and associated Named User, if any: * Creation date and time * Last registration or modified date and time * Associated channel types 1. For more information about a channel or Named User, select the right arrow icon (→). See the next two sections for descriptions of those views. ![Email channel and Named User returned for a Channel ID lookup](https://www.airship.com/docs/images/contact-mgmt-search_hu_5084ed6fbea1c679.webp) *Email channel and Named User returned for a Channel ID lookup* ### Viewing channel details 1. [Look up a contact](#looking-up-a-contact). 1. For a returned channel, select the right arrow icon (→). Data displayed for each channel: * Identifier * [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) * Creation and last registration dates and times * Installation status * Opt-in status * App, Web, and Open channels display **Opted-In** or **Opted-Out**. **Background Enabled** or **Background Disabled** appears for App channel background push. * SMS channels have a check box, which is checked if opted in. You can check/uncheck the box to change the status. * Email channels have **Commercial** and **Transactional** check boxes, which are checked if opted in. You can check/uncheck the boxes to change the status. If an email channel is suppressed, you will see a button for removing suppression. See [Removing email suppression](#removing-email-suppression). * Tracking status — Email channels have **Open tracking** and **Click tracking** check boxes, which are checked if opted-in. You can check/uncheck the boxes to change the status. * In a holdout group — This label appears if the channel is currently excluded from messaging as part of an active [Holdout Experiment](https://www.airship.com/docs/reference/glossary/#holdout_experiment). ![Details for Email, SMS, iOS, and Web channels](https://www.airship.com/docs/images/contact-mgmt-channels_hu_1d4c0401b9a772dd.webp) *Details for Email, SMS, iOS, and Web channels* 1. Select the down arrow icon (▼) for information associated with the channel. Data displayed per tabbed section: | Section | Description | | --- | --- | | **Channel detail** | Channel ID, push address, and aliases, if any. Email channels also display commercial and transactional opt-in/out dates, if any. | | **Channel tags** | [Tags](https://www.airship.com/docs/reference/glossary/#tag) | | **Tag groups** | [Tag Groups](https://www.airship.com/docs/reference/glossary/#tag_group) and the tags within the groups | | **Attributes** | [Attribute](https://www.airship.com/docs/reference/glossary/#attributes) IDs, types, and values. For JSON Attributes, the ID is formatted as ``. See [JSON Attributes](https://www.airship.com/docs/guides/audience/attributes/about/#json-attributes) in _About Attributes_. | | **Device properties** | [Device Properties](https://www.airship.com/docs/reference/glossary/#device_properties) Tag Groups and the tags within the groups | | **Subscription lists** | [Subscription List](https://www.airship.com/docs/reference/glossary/#subscription_list) IDs | | **Holdout group history** | The [Holdout Experiment](https://www.airship.com/docs/reference/glossary/#holdout_experiment) name and start and end times when the user was excluded from messaging | ### Viewing Named User details To view information about a Named User: 1. [Look up a contact](#looking-up-a-contact). 1. For a returned Named User, select the right arrow icon (→). Data displayed per tabbed section: | Section | Description | | --- | --- | | **Channels** | Each channel is listed separately. The appearance and functionality is identical to the [detail view for a channel](#viewing-channel-details). | | **User Tag Groups** | [Tag groups](https://www.airship.com/docs/reference/glossary/#tag_group) and the tags within a group. | | **Attributes** | [Attribute](https://www.airship.com/docs/reference/glossary/#attributes) IDs, types, and values. For JSON Attributes, the ID is formatted as ``. See [JSON Attributes](https://www.airship.com/docs/guides/audience/attributes/about/#json-attributes) in _About Attributes_. | | **Message History** | A list of messages sent to the user within the last 30 days. | ![Named User details](https://www.airship.com/docs/images/contact-mgmt-named-user_hu_7ff4265973b8ef05.webp) *Named User details* ## Creating a Named User [AXP](https://www.airship.com/docs/reference/feature-packages/) If a channel is not yet associated with a Named User, you can manually create one: 1. [Look up a contact](#looking-up-a-contact). 1. For a returned channel, select the right arrow icon (→). 1. Select **Create Named User**. 1. Enter the user name. 1. Select **Submit**. The channel and any channels associated with it will be associated with the Named User. ## Associating channels with a Named User [AXP](https://www.airship.com/docs/reference/feature-packages/) To add a channel: 1. [Look up a contact](#looking-up-a-contact). 1. For a returned Named User, select the right arrow icon (→). 1. Select **Add/edit channels**. 1. Enter a contact identifier and select **Look up**. 1. Select **+ Add channel** for an individual channel. * If the channel you want to add is already associated with a Named User, both the individual channel and its currently associated Named User will be listed in the results. * If you searched for a Named User, or if a Named User was returned when searching for a different identifier, select **▼ View channels** to see its associated channels. Select **+ Add channel** to disassociate the channel from its current Named User and associate it with the Named User you are editing. To disassociate a channel from a Named User: 1. [Look up a contact](#looking-up-a-contact). 1. For a returned Named User, select the right arrow icon (→). 1. Select **Add/edit channels**. 1. Select **Remove** for a channel. ## Deleting a channel To remove a channel from your Airship records: 1. [Look up a contact](#looking-up-a-contact). 1. For a returned channel, select the right arrow icon (→). Make sure to select a channel, not a Named User. The option to delete a channel is not available when viewing details for a channel within a Named User record. 1. Select **Delete this channel**. ## Deleting a contact To remove a contact and its associated channels from your Airship records: 1. [Look up a contact](#looking-up-a-contact). 1. Select the right arrow icon (→) for a channel or Named User. 1. Select **Delete this contact**. ## Removing email suppression To remove the [suppression state](https://www.airship.com/docs/developer/api-integrations/email/bounce-handling/) for an email channel: 1. [Look up a contact](#looking-up-a-contact). 1. For a returned email channel, select the right arrow icon (→). 1. Select the information icon (ⓘ) next to the Opt-in Status check box to view the complaint reason. 1. Select **Remove suppression**. The button is only present if the channel is suppressed. The [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) [Email registration event](https://www.airship.com/docs/developer/rest-api/connect/schemas/email-compliance-events/#registration) for this action includes the username of the user who removed suppression. After removing suppression, you must also opt the channel back in to messaging before they can receive email from you again. # 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 [Channel](https://www.airship.com/docs/reference/glossary/#channel_dev) 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 Coordination](https://www.airship.com/docs/reference/glossary/#channel_coordination) 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](https://www.airship.com/docs/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 Analytics](https://www.airship.com/docs/reference/glossary/#pa) and [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) 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 100 associated channels, but a channel can only be associated with a single named user. A [Named User object](https://www.airship.com/docs/developer/rest-api/ua/schemas/named-user/#nameduserresponsebody) 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 [Attributes](https://www.airship.com/docs/reference/glossary/#attributes) 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](https://www.airship.com/docs/developer/rest-api/ua/schemas/channels/#channellistingobject) associated with the named user. A single named user can contain up to 100 channels. **Example named user object** ```json { "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. > **Important:** * A 403 Forbidden response is returned if named user association is attempted when client-side association is disabled. > > * 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. To change your Named User setting: 1. Next to your project name, select the dropdown menu (▼), then **Settings**. 1. Under **Project settings**, select **Named Users**. 1. Enable or disable **Allow named users to be set from devices**. ## Associating Channels with Named Users {#associate} 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](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#associatenameduser). > **Note:** 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 {#sdk} By default, the [SDK associates named users on the client side](#client-side-named-user-association) 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](https://www.airship.com/docs/sdk-topics/contacts/) in the SDK developer documentation. * [Named Users](https://www.airship.com/docs/developer/sdk-integration/web/segmentation/#named-users) in *Segmentation for the Web SDK* > **Note:** Set up automatic disassociation calls to avoid running into maximum number of channels per named user (100). You can easily reach this limit if there are multiple developers testing on multiple devices. ### Using the API {#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 User Association endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#associatenameduser) for more information about the required fields for different channel types. **Associate an email channel with a named user** ```http POST /api/named_users/associate HTTP/1.1 Authorization: Basic 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 {#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](https://www.airship.com/docs/guides/audience/segmentation/sftp-upload/) 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](https://www.airship.com/docs/reference/messages/csv-formatting/#named-user-association). 1. Go to *Audience » Attributes » Upload Named User Data*. You can click **Download sample CSV file ** to see a formatted file. 1. Click **Choose file** and select your CSV. 1. Click **Upload**. --- Your dashboard and SFTP uploads are listed in *Audience » Attributes » Upload History*. The list also includes [Attribute uploads](https://www.airship.com/docs/guides/audience/attributes/setting/#csv-file). 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](https://www.airship.com/docs/guides/audience/segmentation/sftp-upload/). 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.

**Target a named user by tag on their preferred channel** ```http POST /api/push HTTP/1.1 Authorization: Basic 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.

**Attributes at the Named User level can be used to target any Channel associated with a Named User:**
```mermaid 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 ```

  • 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.

**Attributes at the Channel level are limited to that Channel:**
```mermaid graph LR A[App Channel
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 Coordination](https://www.airship.com/docs/reference/glossary/#channel_coordination) 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** ```json { "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 Coordination](https://www.airship.com/docs/reference/glossary/#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](https://www.airship.com/docs/guides/features/orchestration-experimentation/channel-coordination/) for more information about available Channel Coordination strategies. **Message users on their last active channel** ```http POST /api/push HTTP/1.1 Authorization: Basic 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" ] } ``` # Tags > Tags are metadata that you can associate with channels or named users to help you organize and target your audience. Tag groups categorize your tags. ## About tags Tags are descriptive terms indicating user preferences or other categorizations. They are used to track information about your audience and are set at the [Channel](https://www.airship.com/docs/reference/glossary/#channel_dev) and [Named User](https://www.airship.com/docs/reference/glossary/#named_user) level. You can also trigger messages based on a tag change. Generally, you want to set tags on your audience in response to things they do, like: * Subscribing to a particular service * Checking a box on your website indicating that they like a particular product * Engaging with a message from you by following a link * Viewing a page in your app For example, if members of your audience indicate that they like movies, you might assign those users a `likes_movies` tag in the `interests` group. You could then target users by interest, sending a specific message to the subset of your users with the `likes_movies` tag. Users without the tag won't get your message. --- In the API, tags appear in `tags` and `tag_groups` objects. **`likes_movies` example:** ```json { "audience": { "tag": "likes_movies", "group": "interests" }, "notification": { "alert": "Let's go to the movies sometime", "actions": { "add_tag": ["tapped_the_notification"] } }, "device_types": [ "ios", "android" ] } } ``` ## About tag groups {#tag-groups} All tags are categorized in *tag groups*. There are three types: | Tag group type | Tag group name | Creator | Tag source | Editing | | --- | --- | --- | --- | --- | | Device property tags| Various | Airship | SDK or API | You cannot edit the tags or the tag group names. | | Custom | Various | You | SDK or manually set | You can manage all the tags and tag group names. Maximum 100 custom tag groups. | | Primary device tags | `device` | Airship | SDK or manually set | You cannot edit the tag group name, but you can add and remove tags from `device`. Any tag set without defining a tag group will default to the `device` tag group. | ### Device property tags *Device properties* are metadata representing the default attributes and property tags of a device, such as language and time zone settings, OS and browser versions, and notification opt-in status. Device properties are used for audience segmentation. The data used for the tags and attributes is collected automatically from the Airship SDKs, and are updated daily. There are multiple device property tag groups, and they all begin with `ua_`. You generally use device property tags indirectly. For example, locale can determine when a user will receive a localized message, and time zone can determine when a user receives a message scheduled for delivery using local time. Those are both used by Airship when sending a message without selecting the tag in audience segmentation. > **Note:** You cannot modify device property tags or tag groups. See reference: [Device Property Tags](https://www.airship.com/docs/reference/data-collection/device-properties/#device-property-tags). ### Primary device tags {#device-tags} Primary device tags (or just "device tags") are in a single tag group: `device`. This tag group contains any tag set without defining a tag group. Typically this means tags set through the SDK based on user interaction with your app. For example, if you send a push that sets a tag on a user after they tap it, then that tag is added to the `device` tags group. In general, you can set and target these tags on a channel when you do not specify a tag group. > **Important:** While you can set device tags through the API or dashboard by targeting the `device` tag group, **device tags can be overwritten by the SDK**. Therefore it is strongly recommended that you use create and use custom tag groups when setting tags. > **Note:** Primary device tags are associated with channel IDs only, not named users. **Channel with device tags:** ```http HTTP/1.1 200 OK Content-Type: application/vnd.urbanairship+json; version=3 { "ok": true, "channel": { "channel_id": "01234567-890a-bcde-f012-3456789abc0", "device_type": "ios", "installed": true, "opt_in": false, "background": true, "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660", "created": "2013-08-08T20:41:06", "last_registration": "2014-05-01T18:00:27", "named_user_id": "some_id_that_maps_to_your_systems", "alias": null, "tags": [ "tag1", "tag2" ], "tag_groups": { "tag_group_1": ["tag1", "tag2"], "tag_group_2": ["tag1", "tag2"] }, "ios": { "badge": 0, "quiettime": { "start": null, "end": null }, "tz": "America/Los_Angeles" } } } ``` ### Custom tag groups {#custom-tag-groups} In general, we suggest that you use custom tag groups for the data you want to track (e.g., purchase history or CRM data) so that it's easier to take advantage of tags at both the channel and named user levels. You must create tag groups in the dashboard before you can use the tag group to set tags on your audience. After you create your tag groups, you can start setting tags on channels and named users. Any method that sets tags will also create a tag if it doesn't already exist. You can also use the tags for audience targeting. > **Note:** You can manually relate a tag group to an external source of data, however there is no *actual* connection between the tag group and your external database. > > We recommend that you name your tag groups to reflect their data source for producing tagging information. For example, if you have a CRM database that records when users click an *Interested in Partner Offers* checkbox, you might add a `partner` tag in a `crm` tag group on those users' devices. ### Creating custom tag groups > **Warning:** You cannot delete tag groups, nor can you edit the *Group Key* field or *Allow these tags to be set only from your server* security setting. Check that your *Group Key* and security setting are correct before saving your tag group. You can create up to 100 custom tag groups. 1. Go to *Audience » Tags » Tag Groups*. 1. Click **Create tag group** and enter: * **Name** — A friendly name for the tag group that will help you recognize the tag group in other places. Pick something easily understandable that describes the associated database, e.g., "Loyalty Database Tags." * **Description** — Additional information about the tag group, describing the source and purpose for the tag group, if necessary. * **Group Key** — The unique ID for the tag group, and how you will reference the tag group in API calls. It is strongly recommended that you exclusively use lowercase ASCII characters. Spaces are not allowed in a group key. Example: `pos-database`. > **Note:** Airship reserves tag groups prefixed with `ua_`. Any tag groups you might create with that prefix will not function. 1. (Optional) Enable *Allow these tags to be set only from your server*. This increases security by requiring tag read-write operations to be authenticated with your master secret key. > **Note:** If you do not enable this setting, tags can be read and written from an app using only the application secret, potentially allowing attackers to use your app secret to read or set their own tags. Whether or not your app will benefit from added security depends on the use case. If preventing attackers from reading or setting their own device tags is absolutely critical, enable this setting. 1. Click **Create tag group**. #### Managing custom tag groups You can enable/disable tag groups and edit names and descriptions. 1. Go to *Audience » Tags » Tag Groups*. You can search for tag groups by name or group key. 1. Click the edit icon ( ) for a tag group. 1. Check or uncheck the box for *Enable this Tag Group*, or edit the name or description. 1. Click **Update tag group**. ## Setting tags on your audience You do not need to create tags before you set them. Any method for setting a tag will also create the tag if it doesn't already exist. ### User action You can set and/or remove tags on your audience when they interact with your push notifications, web push notifications, and in-app messages. This is configured after setting the message [Action](https://www.airship.com/docs/reference/glossary/#action). You can also set and/or remove tags when they press an image or button in your message. Tag actions are a simple way to track audience engagement. Set tags to group your audience based on their engagement with your messages, determining the best ways to engage with different sets of users. You can also compare a total message audience with the tags changed within an audience to see how well your call to action performed, and determine the percentage of your audience moving through your funnel. > **Note:** Setting or removing tags when users interact with your message is limited to Primary Device Tags. You can add or remove tags when the following actions occur: | Content | Message action | Button press | Image press | | --- | :---: | :---: | :---: | | [Push Notification](https://www.airship.com/docs/reference/glossary/#push_notification) | ✓ | ✓ | | | [Web Push Notification](https://www.airship.com/docs/reference/glossary/#web_push_notification) | ✓ | ✓ | | | [In-App Message (standard)](https://www.airship.com/docs/reference/glossary/#in_app_message) | ✓ | ✓ | | | [Message Center](https://www.airship.com/docs/reference/glossary/#message_center) | | ✓ | ✓ | | [Landing page](https://www.airship.com/docs/guides/features/messaging/landing-pages/) | | ✓ | ✓ | | [In-App Automation](https://www.airship.com/docs/reference/glossary/#iaa) | | ✓ | ✓1 | | [Scene](https://www.airship.com/docs/reference/glossary/#scene) | | ✓ | | 1. You must use the drag-and-drop option in the Interactive editor to create the content. Using the API, specify tag actions in the `audience` object. **Push with a tag action** ```http POST /api/push HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "audience": { "tag": "not_it" }, "notification": { "alert": "Tag, you're it!", "actions": { "add_tag": [ "you_are_it" ], "remove_tag": [ "not_it" ] } }, "device_types": [ "android" ] } ``` ### Content display You can add and/or remove tags when a [Scene](https://www.airship.com/docs/reference/glossary/#scene) or [Rich Page](https://www.airship.com/docs/reference/glossary/#rich_page) is displayed. For rich pages, you must use Visual editor to create the content and configure an *Onload* field. ### File upload [AXP](https://www.airship.com/docs/reference/feature-packages/) Bulk add and/or remove tags in custom tag groups by uploading a user list in a CSV file. When using email or SMS identifiers in your CSV file, Airship registers new channels for addresses or MSISDN/sender combinations that are new to your project. Additional fields indicate opt-in statuses so that you can send messages to new channels generated from your CSV upload. If you are assigning tags for custom tag groups, they must already exist in your project. See [Creating custom tag groups](#creating-custom-tag-groups) above. 1. Prepare your CSV file using the guidelines in [Tags CSV Format](https://www.airship.com/docs/reference/messages/csv-formatting/#tags-format). 1. Go to *Audience » Tags » Set tags*. You can click **Download sample CSV** to see a formatted file. 1. Click **Choose file** and select your CSV. 1. Select *Add* or *Remove*, enter a tag name in the search field, then: * If searching for an **existing tag**, click to select from the search results. Search for existing tags returns all custom tag groups that contain that tag. * If creating a **new tag**, click **Create new tag: [search term]**, enter a custom tag group name in the search field that appears, then select from the search results. 1. Click **Set tags**. File upload history is in *Audience » Tags » Upload History*. The latest upload is listed first, with columns for: * File name * User name — The user who performed the upload in the dashboard * Upload date * Tags changed — Counts for the number of tags added and removed. Select the info icon (ⓘ) for a list of all tags, tag groups, and `+` (added) or `-` (removed) indicators. * Rows processed * Rows skipped * Status — Processed, Processed with errors, Processing, or Failed. For status *Processed with errors*, select the download icon ( ) to download the error list. #### 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.

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 Tag list that adds Tag A to a channel, Tag A will still exist on the channel after list deletion. ### SDK You can use the SDK to set tags on channels as your audience navigates your app and website. See our [SDK](https://www.airship.com/docs/sdk-topics/tags/) documentation for code samples and additional information. ### API Use the API to set tags on channels server-side. You might do this with integrations or for your SMS, email, and Open Channels — channels that don't rely on the Airship SDK. You can set tags on your audience using these endpoints: * [Named Users Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifynamedusertags) * [Channel Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifychanneltags) * [Open Identifiers Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifyopenchanneltags) * [Email Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifyemailchanneltags) #### 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** ```http POST /api/push HTTP/1.1 Authorization: Basic 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" ] } ```

## Targeting users You can include Attributes when using the **Target by conditions** and **Target specific users** audience options for messages and experiments. You can also create [Segments](https://www.airship.com/docs/reference/glossary/#segment) instead of having to recreate your audience selections. Both use the same process. Tags can be combined with other segmentation data, such as events and Attributes. For full instructions and usage locations, see [Segments](https://www.airship.com/docs/guides/audience/segmentation/segments/). In the API, target specific users via the `"audience"` object. See [API: Audience Selection](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/). Using the API, when a tag group is assigned to a channel or named user, you target all channels or named users with the same tag and tag group. This example targets channels with the tag `blue` in the group `fish_colors`: ```json { "audience": { "tag": "blue", "group": "fish_colors" } } ``` ## Creating segments Create [Segments](https://www.airship.com/docs/reference/glossary/#segment) based on tags and tag groups you applied to channels: * [API: Segments](https://www.airship.com/docs/developer/rest-api/ua/operations/segments/) * [Dashboard: Segments](https://www.airship.com/docs/guides/audience/segmentation/segments/) ## Triggering automation and sequences Tag changes can be used as triggers for automation and [Sequences](https://www.airship.com/docs/reference/glossary/#sequence), and you can use tag actions to trigger follow-up messages. You can also use tags as [Conditions](https://www.airship.com/docs/reference/glossary/#conditions_event_option) for both. See: * [Tag Change](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#tag-change) in *Automation and Sequence Triggers* * [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create-automation/#conditions) in the Setup section of *Create an Automation* * [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create/add-messages/#conditions) in *Add Messages to a Sequence* # Target Specific Users (Legacy) > Choose a recipient group based on tags, predefined segments, audience lists, and more. When selecting your audience in the Message and A/B Test composers, you can *Target Specific Users* based on various [target data](#target-data). See also: [Segmenting Your Audience](https://www.airship.com/docs/guides/audience/segmentation/segmentation/). ## Steps {#steps} 1. Find [target data](#target-data) via search or explore. Your selections appear under Targeted Audience. ![Targeted audience selections](https://www.airship.com/docs/images/audience-any_hu_c85b134f29d9474.webp) *Targeted audience selections* * **Search** 1. Enter a term in the search field, and select from the listed results. To filter results, select the filter menu (▼) and make your selection. ![Searching for Attributes in the audience selector](https://www.airship.com/docs/images/audience-search-attributes_hu_5188843965ad08c0.webp) *Searching for Attributes in the audience selector* 1. (For attributes only) Set an operator determining how you want to evaluate the attribute: *equals*, *does not equal*, *contains*, etc. ![Setting an operator for an Attribute condition](https://www.airship.com/docs/images/attributes-operators_hu_e37145ba1074714b.webp) *Setting an operator for an Attribute condition* * **Explore** 1. Select a [data type](#target-data), and select from the listed results to drill down to your desired target. You can enter a term in the *Filter results* search box to help narrow your choices. ![Exploring audience data types](https://www.airship.com/docs/images/audience-explore_hu_4e05649bdcc389c0.webp) *Exploring audience data types* 1. (Optional) Click **+ Add another target** to add more audience criteria. 1. Select *ALL/ANY* to determine how to evaluate multiple targets.
  • ALL = all criteria must be met (boolean AND)
  • ANY = any criteria must be met (boolean OR)
![Evaluating multiple audience targets with ALL/ANY](https://www.airship.com/docs/images/target-attributes_hu_f45d515f283ed778.webp) *Evaluating multiple audience targets with ALL/ANY* By default Airship only includes audience members meeting ALL the conditions you select. For example, if you selected ALL, with tags `VIP` and `has_pets`, you'd only reach VIP pet owners. If you selected ANY, you’d reach all VIPs and all pet owners. You can create a [Segment](https://www.airship.com/docs/reference/glossary/#segment) to define more complex, nested logic. Now you can complete the remaining steps in the composer. ## Target Data {#target-data} You can specify your message audience by a unique identifier, such as a device ID or email address, or by an identifier that may belong to or include multiple users, such as a tag or audience list. Learn more in [Segmentation](https://www.airship.com/docs/guides/audience/segmentation/segmentation/). | Data type | [Search](#steps) | [Explore](#steps) | | --- | :---: | :---: | | [Attributes](https://www.airship.com/docs/reference/glossary/#attributes) | ✓ | | | [Audience List](https://www.airship.com/docs/reference/glossary/#audience_list) | ✓ | ✓ | | [Device ID](https://www.airship.com/docs/reference/glossary/#device_id) | ✓ | | | [Device Properties](https://www.airship.com/docs/reference/glossary/#device_properties) | ✓ | ✓ | | [Named User](https://www.airship.com/docs/reference/glossary/#named_user) | ✓ | | | [Predicted to Churn](https://www.airship.com/docs/reference/glossary/#predicted_to_churn) | ✓ | ✓ | | [Segment](https://www.airship.com/docs/reference/glossary/#segment) | ✓ | ✓ | | [Sender ID](https://www.airship.com/docs/reference/glossary/#sender_id) | ✓ | ✓ | | [Tags](https://www.airship.com/docs/reference/glossary/#tag) and [Tag Groups](https://www.airship.com/docs/reference/glossary/#tag_group) | ✓ | | > **Note:** Lifecycle audience lists are not supported for Web, Email, SMS, or Open channels. # Preview and test groups > Create audience groups that can be used for previewing personalized content and receiving test messages. A *preview group* is an audience group used for previewing personalized content in the dashboard. Wherever a personalization preview is available, you can select a preview group, and its group members' attributes will appear for any Handlebars references to attributes. You can enable any preview group as a *test group* so you can send test messages to its group members. These messages appear as tests in Messages Overview. By keeping a saved list of approved test users in Airship, you can be sure that your test messages only reach an approved, in-house list of users. You might limit your test group to company employees such as Product staff, Development team, etc. ## Requirements, validation, and registration When adding users to a group, you must enter an ID: [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id), email address, or [MSISDN](https://www.airship.com/docs/reference/glossary/#msisdn). The ID is used for rendering attributes in personalization previews and where test messages will be sent. The ID is validated upon entry, and you will see errors if these requirements are not met: * Your project must be already be configured for the [Channel (Engagement)](https://www.airship.com/docs/reference/glossary/#channel_engage) for an entered ID. * Channel IDs must exist for the project. * MSISDNs must be for SMS channels that exist for the project. You can add any email address, and an email channel will be registered for the project. ## Creating a new group You can create up to 20 groups. You cannot change the group name and Test Group setting after creating the group, but you can delete the group and create a new one. Also, you cannot change a user ID later, but you can [add and remove users from the group](#adding-editing-and-removing-group-members). > **Tip:** Make sure to use IDs that are valid for the group's intended purpose. For example, if you will be sending push notifications to the group, enter a Channel ID for an iOS or Android Channel. 1. Select the **Audience** menu, then **Preview and Test Groups**. 1. Select **Create group**. 1. Enter a name for the group. 1. (Optional) Enable **Test group**. 1. Select **Save and continue**. 1. For each group member, select **Add user**, then enter a name and Channel ID, email address or MSISDN. If a MSISDN is associated with more than one [Sender ID](https://www.airship.com/docs/reference/glossary/#sender_id), select the one that should be used as the sender of test messages. 1. Select **Done**. After adding a user, you will return to the list of all users in the group. The ID column displays the Channel ID for each user. You cannot view the original email address or MSISDN entered when adding the user. Select **Preview and Test Groups** in the page breadcrumbs to return to the list of all your groups. Select the delete icon (trash) to delete a group. ## Adding, editing, and removing group members 1. Select the **Audience** menu, then **Preview and Test Groups**. 1. Select the edit icon ( ) for a group. 1. Complete the steps for an action: | Action | Steps | | --- | --- | | **Add a user** | Select **Add user** and complete steps as described in [Creating a new group](#creating-a-new-group). | | **Edit a user's name** | Select the edit icon ( ) for a user, change the name, and select **Done**. | | **Delete a user** | Select the delete icon (trash) for a user. | ## Using preview groups See [Previewing personalized content](https://www.airship.com/docs/guides/personalization/previewing/). ## Sending to test groups Messages you send to a test group appear in the Tests view in [Messages Overview](https://www.airship.com/docs/reference/glossary/#messages_overview). You can send to a test group from these locations: | Location | Steps | | --- | --- | | The Audience step in the Message, A/B Test, In-App Automation, and Scene composers | Select **Test Users** and select a test group. You must complete the remaining composer steps and send the message before it is sent to the group. | | The Review step in the Message, Automation, and Sequence composers | Select **Send Test**, select at least one test group, then select **Send**. The message sends immediately. | | The Manage screen in a Sequence | See [Test a message in a Sequence](https://www.airship.com/docs/guides/messaging/messages/sequences/create/test/#test-a-message-in-a-sequence). The message sends immediately. | | The Test Run option in a Sequence | See [Test a sequence](https://www.airship.com/docs/guides/messaging/messages/sequences/create/test/#test-a-sequence). The message sends immediately. | # Track Rich Pages With Google Analytics > Track rich page opens and clicks via Google Analytics. While Airship messaging supports tracking of rich page opens out of the box, you can also track opens and clicks within [Rich Page](https://www.airship.com/docs/reference/glossary/#rich_page) content with a third-party tool like *Google Analytics*. These directions assume you already have created a Google Analytics account. See: * [Message Center content](https://www.airship.com/docs/guides/messaging/messages/content/app/message-center/) * [Landing pages](https://www.airship.com/docs/guides/messaging/messages/content/app/landing-pages/) ## Configure Google Analytics 1. Navigate to the Admin page in [Google Analytics](https://analytics.google.com). 1. In the *Property* column, click **+ Create property**, and name it something like "Airship Rich Pages." 1. Set the Default URL to `https://device-api.urbanairship.com`. 1. Click **Get Tracking ID**, then you will see a page displaying the tracking ID. 1. Note the Tracking ID assigned to this property. ## Track Page Opens To track page opens you need to embed the Google Analytics JavaScript. If you just completed creating a new property, you will already have this page open, and you can skip to step 4. 1. Navigate to the Admin page in [Google Analytics](https://analytics.google.com). 1. In the *Property* column, select your property and click *Tracking Info* then *Tracking Code*. 1. Copy the code from the *Website tracking* section. 1. Paste the code into every page you want to track. Sample code is below. Make sure to replace `YOUR TRACKING ID HERE` with your actual tracking ID. ```html ``` > **Note:** It may take several hours before results appear in Google Analytics. ### View Page Opens Because Airship generates a unique URL for each page per user, you will want to first create a filter so that Google Analytics will roll up your URLs to the page level. 1. Navigate to the Admin page in [Google Analytics](https://analytics.google.com). 1. In the *View* column, click *Filters* then *+ Create Filter*. 1. Set the filter so it looks like this: ![Creating a Google Analytics filter for Airship data](https://www.airship.com/docs/images/ga_filter_hu_bf0aadd4636f8838.webp) *Creating a Google Analytics filter for Airship data* 1. Click **Save**. The filter converts URLs from this format, with user info embedded: ```text https://device-api.urbanairship.com/api/user/3BIi_uawQaa8HShcJJxooA/messages/message/iyHEOIqcTq-drAx78p4FYw/body/ ``` To this, which is how message-level URLs will appear in Google Analytics reports: ```text /api-messages/message/iyHEOIqcTq-drAx78p4FYw/body/ ``` ## Track Link Clicks 1. Paste this code into every page you want to track: ```html ``` You can modify the values of 'category' and 'action' to organize the information in Google Analytics. See [Google's documentation](https://developers.google.com/analytics/devguides/collection/analyticsjs/events) for more information. 1. Wire up the event to your event, passing a unique ID to the `sendLink()` method: ```html Download Now ``` ### View Link Clicks If you are tracking Link Clicks, you can view the events in the Overview or Content sections of the Google Analytics *Realtime* report. # Ad IDs > Optimize your user acquisition and re-marketing campaigns with Ad IDs. # What are Ad IDs? Ad IDs are user-level IDs that are the same for a user over multiple apps on their device. Ad IDs allow marketers to send content and ads to users that have not limited their ad tracking. Other services such as Facebook and Twitter capture the same Ad ID and have ad platforms to target specific users based on Ad IDs. This topic guide covers use cases and technical details on how to send Airship Ad IDs so you can begin to optimize your user acquisition and re-marketing campaigns. # Use Cases Customer acquisition costs for mobile are rising due to low-quality users [churning out](https://www.airship.com/docs/guides/features/intelligence-ai/predictive/predictive-churn/) within a short time frame. It is therefore increasingly critical to focus on your most valuable and loyal users, the ones you've worked hard to acquire, activate, retain, and monetize. What if you could construct an ideal profile based on the characteristics of your most loyal users, then take the profile and say, "I'll have more like them, please"? With Airship messaging and [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa) you can leverage your most valuable users to find similar new users. Grow your audience according to user characteristics that have been most successful for you in the past. > **Tip:** Read the > [Exporting Lists Tutorial](https://www.airship.com/docs/guides/reports/analytics/tasks-queries/export/#ins-tutorial-ad-ids) > to learn how to take action with Performance Analytics using Ad IDs. ## New User Acquisition Using ad platforms such as Facebook and Twitter to leverage the information available in [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa), such as loyal users, as input in to [Facebook's lookalike audience](https://www.facebook.com/business/help/164749007013531?id=401668390442328) helps you find more high-valued users similar to your loyal users. **Examples of valuable data:** * Push opted-in * Interacted with a message * Active for the last 30 days * Completed a goal in your app ## Win-Back and Re-Marketing You can also use Facebook or Twitter Ad platforms to run win-back campaigns for [churned users](https://www.airship.com/docs/guides/features/intelligence-ai/predictive/predictive-churn/) or re-market your product using a custom audience. **Win Back - Example of valuable data:** * Uninstall **Re-marketing - Examples of valuable data:** * New users * Abandoned cart * Browsed product view (non-purchase) * High frequency/recency users # Technical Details > **Warning:** Your app must: > > 1. Send the *limit ad tracking* field from your app, and > 1. Not target users with ads who have *limit ad tracking* enabled. A value of > Unknown or Limit Ad Tracking = Yes or Unknown means you cannot send > ads to these users. See the [SDK Analytics](https://www.airship.com/docs/sdk-topics/analytics/) documentation for details about enabling tracking the Ad ID. ## Attributes {{< glossary_definition "attributes" >}} # About Attributes > {{< glossary_definition "attributes" >}} ## Tags versus Attributes Consider the example below — you want to target fans of the actor Chris Pine. To accomplish this, you specify an audience of users with the [Tag](https://www.airship.com/docs/reference/glossary/#tag) `chris_pine`. Either a user has this tag, or not. **Note:** These API examples can also be used in the dashboard. **Tag audience** ```json { "audience": { "tag": "chris_pine" } } ``` But let's say you wanted to target fans of **All The Chrises**: Chris Pine, Chris Evans, Chris Pratt, and Chris Hemsworth. With Attributes, you can set your audience to target users whose `favorite_actor` Attribute `contains` the value `chris`, and you will reach all the Chris fans. **Attributes audience** ```json { "audience": { "attribute": "favorite_actor", "operator": "contains", "value": "chris" } } ``` It's a silly example, but hopefully you can begin to see the power of comparison operators for Attributes. ## Attribute types User information can be stored in an Attribute as text or as a number, date, or JSON object. Each Attribute type is named for the schema that defines what values it accepts. Text, Number, and Date schemas are determined by Airship. You provide your own schema for JSON Attributes. Values accepted for each Attribute type: | Attribute type | Value format | Comments | | --- | --- | --- | | **Text** | String | Text strings can be a maximum of 255 characters. | | **Number** | Number or float value | When setting Number Attributes, you can provide your value as an integer, float, or string. | | **Date** | ISO 8601 date-time formatted string: `YYYY-MM-DDTHH:MM:SS` | You can set an offset by appending the date-time with `+HH:MM`. For example, `2020-07-20T12:35:42+08:00`. Date Attributes are converted to and stored as UTC. | | **JSON** | An object containing one or more string, number, date, or boolean key-value pairs, individually or within objects or arrays | JSON Attributes are not available in [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa). See following page section for additional information. | ### JSON Attributes JSON Attributes are data objects containing one or more string, number, date, or boolean key-value pairs. The pairs can be added individually or within objects or arrays. You can think of them as collections of information you can assign to a user. Example use cases: * **Retailer** — Store user preferences and send sale or discount messages about items you know a user will be interested in and with personalized content for their preferred brands, colors, etc. * **Airline** — Store a user's booking information and send confirmation and update messages leading up to, during, and after their trip. Messages would contain their confirmation code, flight numbers, origin and destination airport codes, and departure and arrival times. For each JSON Attribute, you create a template for the structure and what data to store. The template is the *schema* and the data is defined as *properties*. Using the above airline use case, you could have an Attribute with ID `reservation` and create a schema for the confirmation code and lists of like data types (departures and arrivals) with properties for flight numbers, airport codes, and times. In addition to the properties defined in your provided schema, each JSON Attribute has a property `exp` for its expiration date, represented as the number of seconds since the epoch (January 1st, 1970). After expiration, Airship ignores the Attribute where used in segmentation and personalization. When setting a JSON Attribute on a user, if a value for `exp` is not provided, Airship automatically sets a value of 90 days from the current date and time. The maximum expiry delay for a JSON Attribute is 731 days. Each instance of setting a JSON Attribute on a user is defined by an *instance ID*, which is used as a reference for the property values set for that user. The following describes associating the data with users and targeting and personalization options: | Topic | How it works | Airline use case example | | --- | --- | --- | | **Setting the Attribute on your audience** | Use the API to set JSON Attributes on a user, specifying an instance ID and values for properties. | When a user books a round-trip flight, you could assign the `reservation` Attribute with instance ID `a001`. The JSON data assigned for instance `reservation#a001` would contain a list of each flight leg going to the destination and each returning flight leg. | | **Targeting the Attribute** | You target a JSON Attribute's properties, not the object as a whole. All instances of the Attribute are evaluated for matches. Any user that matches the target is included in the message audience. | For a flight update message, you could target any user with the Attribute `reservation` where the initial leg of their trip departs from airport `PDX`. Any user with that Attribute and value `PDX` for the airport code property would be included in the message audience. | | **Personalizing content** | In message content, you can reference JSON Attributes by instance ID or evaluate all instances of the Attribute. In both cases, the message content populates with the property values set for a user. | In a flight update message, you could reference `reservation` properties, and the message would contain user-specific details about how the change affects their trip. | ## Categories, data sources, and setup Attributes can come from the Airship SDKs, users, and you. Data sources, descriptions, and setup per Attribute category: | Category | Data source | Description | Setup | | --- | --- | --- | --- | | **Default** | Airship SDKs | Airship automatically sets Default Attributes on your audience. See [Default Attributes](https://www.airship.com/docs/reference/data-collection/attributes/#default-attributes) in the _Attributes Reference_. | None. | | **NPS survey** | User answers to Net Promoter Score (NPS) surveys in [Scenes](https://www.airship.com/docs/reference/glossary/#scene) | Airship automatically generates Attributes based on the NPS score or category. See [NPS Segmentation](https://www.airship.com/docs/guides/features/messaging/scenes/surveys-stories/#nps-segmentation) in _Surveys and Stories_ and [NPS survey Attributes](https://www.airship.com/docs/reference/data-collection/attributes/#nps-survey-attributes) in the _Attributes Reference_. | None. | | **Predefined** | Customer | Preformatted Text and Number Attributes you can use to ensure consistency across reports and [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa). For example, ID `first_name` for first name, and ID `last_name` for last name. See [Predefined Attributes](https://www.airship.com/docs/reference/data-collection/attributes/#predefined-attributes) in the _Attributes Reference_. | Add Attributes in your project settings then set them on your audience. | | **Custom** | Customer | You can add any Attribute type to your project. | Add Attributes in your project settings then set them on your audience. | | **Zero-copy data integration** | Data partner | Directly access user data from external systems. The data remains in its original location instead of being copied or imported into Airship. | See [Zero-copy data integration](https://www.airship.com/docs/guides/features/data-integration/zero-copy-data-integration/). | > **Warning:** To target users based on a unique user ID or other external identifier, do not use Custom Attributes. Instead, target [Named User](https://www.airship.com/docs/reference/glossary/#named_user). > **Tip:** You can store responses to single choice questions in [Scenes](https://www.airship.com/docs/reference/glossary/#scene) as Attributes. > > See the [Question content element](https://www.airship.com/docs/guides/messaging/editors/native/elements/#question) in *Configuring Scene content*. ## Personalization You can use Attributes in a message body to personalize content for each user. See [Personalizing messages using Attributes](https://www.airship.com/docs/guides/personalization/sources/attributes/). # Adding Attributes to your project > Before you can target Attributes, you must add some types to your project. You must add Predefined and Custom Attributes to your project before you can set them on your audience for targeting. You can add up to 250 Attributes per project.

After adding Attributes, allow at least 10 minutes before setting their values. This delay ensures proper processing of the Attributes within Airship.

No setup is required for Default and NPS survey Attributes. You can go straight to [Targeting your audience using Attributes](https://www.airship.com/docs/guides/audience/attributes/targeting/). Similarly, Attributes from [Zero-copy data integration](https://www.airship.com/docs/guides/features/data-integration/zero-copy-data-integration/) are available for targeting once Airship completes your project configuration. ## Add Text, Number, and Date Attributes Follow these steps to add text, number, or date Attributes to your project: 1. Go to **Audience**, then **Attributes**, then **Attribute List**. 1. Select **Create Attribute**. 1. Search for the Attribute you want to add. If it matches a [Predefined Attribute](https://www.airship.com/docs/reference/data-collection/attributes/#predefined-attributes), select from the results. Results do not include Predefined Attributes that have been [archived](https://www.airship.com/docs/guides/audience/attributes/managing/) or already added. 1. Complete the fields: | Field | Description | Steps | | --- | --- | --- | | **Attribute ID** | The key that Airship uses to reference the Attribute in the SDKs and API. Letters, numbers, and underscores only, 64 characters maximum. The `ua_` prefix is reserved by Airship, so you cannot include it in the ID. Cannot be edited for Predefined Attributes. | Enter text. | | **Name** | A human-friendly name to help you organize and identify your Attributes in the dashboard. Accepts all characters, 64 characters maximum. | Enter text. | | **Type** | Determines the format of the Attribute value: Text, Number, or Date. Cannot be edited for Predefined Attributes. | Select a type. | > **Important:** * Names and IDs must be unique. > * Attribute IDs are case sensitive. If your Attributes exist in an external system, make sure they are always the same case in both systems. > * We recommend using lowercase characters with underscores for Attribute IDs. For example, `my_text_attribute`. > * You cannot edit a Custom Attribute's ID or type after saving. 1. Select **Add**. ## Add JSON Attributes When adding a JSON Attribute, you must define the object's data structure in a schema. An object is a collection of properties defined as key-value pairs. The values can be strings, numbers, dates, booleans, objects, or arrays. An array is an ordered collection of values. A JSON object allows for nested objects and arrays, so it can contain an array of properties, and those properties can themselves be objects containing more properties and arrays of properties. You can manually enter a schema or automatically generate a schema by uploading a sample .json file. For upload: * The value data determines the value types and will be removed. * Array value type is determined based on the first element in an array, so when using an array with more than one type, the array is converted to a single type based on the first element. For example, the array `["hi", true, 3]` will create an array of strings. * Empty arrays, objects without keys, and keys with empty arrays or objects will be ignored. You can assign any property a more readable name, like "Flight number" or "Reservation code", as an alias. When creating a [Segment](https://www.airship.com/docs/reference/glossary/#segment) targeting a JSON Attribute, you can select the alias from a menu instead of having to locate the property within the JSON schema. Aliases are supported in the dashboard only. 1. Go to **Audience**, then **Attributes**, then **Attribute List**. 1. Select **Create Attribute**. 1. Complete the fields: | Field | Description | Steps | | --- | --- | --- | | **Attribute ID** | A portion of the key that Airship uses to reference the Attribute in the SDKs and API. Letters, numbers, and underscores only, 64 characters maximum. The `ua_` prefix is reserved by Airship, so you cannot include it in the ID. | Enter text. | | **Name** | A portion of the key that Airship uses to reference the Attribute in the SDKs and API. The name is also used to help you organize and identify your Attributes in the dashboard. Letters, numbers, and underscores only, 64 characters maximum. | Enter text. | | **Type** | Determines the format of the Attribute value. | Select JSON. | > **Important:** * Names and IDs must be unique. > * Attribute IDs are case sensitive. If your Attributes exist in an external system, make sure they are always the same case in both systems. > * We recommend using lowercase characters with underscores for Attribute IDs. For example, `my_text_attribute`. > * You cannot edit a Custom Attribute's ID or type after saving. > **Tip:** You can select **Add** now to save the Attribute, then edit and set up the schema later. 1. (To automatically generate a schema) Select **Upload**, then upload your sample .json file. 1. (To manually create a schema) Select **Create schema**. 1. Edit the schema: | Option | Steps | | --- | --- | | **Add a property** | Select the add icon (+), enter a name, select a value type, then select the check mark. You must also select a value type for each array. | | **Remove a property or object** | Hover over the item, then select the remove icon (trash). | 1. (Optional) Create aliases: 1. Under **Aliases**, select the add icon (+). 1. Enter a name for the alias. 1. Select a property in the schema. Its path will appear next to the alias. 1. (Optional for arrays in the path) Select **First** or **Last** to specify the first or last item in the array. Defaults to **Any**. 1. Select the check mark to save. 1. Repeat for additional aliases. 1. Select **Save JSON Schema**. 1. Select **Add**. # Setting and removing Attributes > Setting and removing Attributes varies per Attribute type. Setting Attributes on Named Users is recommended. For Predefined and Custom Attributes, you must set them on your audience after adding them to your project. > **Important:** You must add Custom and Predefined Attributes to your project before setting them on users. Otherwise, setting those Attributes will result in an error. See [Adding Attributes to your project](https://www.airship.com/docs/guides/audience/attributes/adding/). > > JSON Attributes can only be set using the API. No setup is required for Default and NPS survey Attributes. You can go straight to [Targeting your audience using Attributes](https://www.airship.com/docs/guides/audience/attributes/targeting/). Similarly, Attributes from [Zero-copy data integration](https://www.airship.com/docs/guides/features/data-integration/zero-copy-data-integration/) are available for targeting once Airship completes your project configuration. ## Channels versus 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.

**Attributes at the Named User level can be used to target any Channel associated with a Named User:**
```mermaid 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 ```

  • 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.

**Attributes at the Channel level are limited to that Channel:**
```mermaid graph LR A[App Channel
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
## Required delay before setting Attribute values

After adding Attributes, allow at least 10 minutes before setting their values. This delay ensures proper processing of the Attributes within Airship.

## Setting and removing Text, Number, and Date Attributes You can set and remove Text, Number, and Date Attributes using: * CSV file upload in the dashboard * CSV file transfer using SFTP * App and Web SDKs * Channels and Named Users APIs Use these formats when setting each Attribute type: | Type | Format | | --- | --- | | **Text** | String. When setting Text Attributes using a CSV, you do not need to wrap the value in quotes. | | **Number** | Number, float value, or string | | **Date** | ISO 8601 date-time formatted string: `YYYY-MM-DDTHH:MM:SS`. Set an offset by appending the date-time with `+HH:MM`. For example, `2020-07-20T12:35:42+08:00`. | ### CSV file First, create a list of users and their Attributes in a CSV file. Prepare your file using the guidelines in [Attributes CSV Format](https://www.airship.com/docs/reference/messages/csv-formatting/#attributes) in the *CSV Formatting Reference*. When using email or SMS identifiers in your CSV file, Airship registers new Channels for addresses or MSISDN/sender combinations that are new to your project. Additional fields indicate opt-in statuses, so that you can send messages to new Channels generated from your CSV upload. All values in CSV uploads, including numbers, are represented as strings and cannot be used with [math helpers](https://www.airship.com/docs/guides/personalization/handlebars/math-helpers/). Next, transfer the file using SFTP or upload it in the dashboard. Follow the steps in [SFTP upload for CSV files](https://www.airship.com/docs/guides/audience/segmentation/sftp-upload/), or follow these steps for dashboard upload: 1. Go to **Audience**, then **Attributes**, then **Upload Attribute Data**. 1. For **Upload Type**, select which file type you prepared, **Attributes CSV** or **Attributes Snapshot CSV**. 1. Select **Choose file** and select your file. 1. Select **Upload**. To see your upload and SFTP transfer status, select **Upload History**. See [Viewing upload history](https://www.airship.com/docs/guides/audience/attributes/managing/#viewing-upload-history) in *Managing Attributes*. #### 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 an Attributes list is the same whether uploaded in the Airship dashboard or [using SFTP](https://www.airship.com/docs/guides/audience/segmentation/sftp-upload/). 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 an Attribute list that adds Attribute A to a Channel, Attribute A will still exist on the Channel after list deletion. ### SDK To set or remove Attributes on a Channel or a Contact, use the Channel or Contact classes in our SDKs: * **iOS** —  [Contact](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/airshipcontact) , [Channel](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/airshipchannel) * **Android** — [Channel](https://www.airship.com/docs/reference/libraries/android-kotlin/latest/urbanairship-core/com.urbanairship.channel/-airship-channel/index.html), [Contact](https://www.airship.com/docs/reference/libraries/android-kotlin/latest/urbanairship-core/com.urbanairship.contacts/-contact/index.html) * **Web** — [Channel](https://www.airship.com/docs/reference/libraries/web-notify-sdk/v2-latest/UaSDK.Channel.html#editAttributes), [Contact](https://www.airship.com/docs/reference/libraries/web-notify-sdk/v2-latest/UaSDK.Contact.html#editAttributes) The code examples below show how to set Attributes using the provided methods. See the [SDK docs](https://www.airship.com/docs/sdk-topics/attributes/) for more details. #### Android Java ```java Airship.getChannel().editAttributes() .setAttribute("average_rating", 4.99) .setAttribute("last_product_purchased", "A1234567") .removeAttribute("purchase_pending") .apply(); ``` #### iOS Swift ```swift Airship.channel.editAttributes { editor in editor.set(string: "cauldron", attribute: "last_product_purchased") editor.set(number: 4.99, attribute: "average_rating") editor.remove("purchase_pending") } ``` #### iOS Objective-C ```obj-c [UAirship.channel editAttributes:^(UAAttributesEditor * editor) { [editor setString:@"cauldron" attribute:@"last_product_purchased"]; [editor setNumber:@(4.99) attribute:@"average_rating"]; [editor removeAttribute:@"purchase_pending"]; }]; ``` **Setting Attributes for Web** ```js const editor = channel.editAttributes() await editor .set("my_attribute", "some_value") .remove("other_attribute") .apply() ``` ### API You can set Attribute values from external sources, such as a CRM or data warehouse, using the Channels and Named Users APIs: * [Set or Remove Attributes on Channels](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#modifychannelattributes) * [Set or Remove Attributes on Named Users](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#modifynameduserattributes) Use `set` or `remove` for the `action` value. Use the Attribute ID as the `key` value. **Setting two Attributes on a Channel and removing another** ```http POST /api/channels/attributes HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "audience": { "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881" }, "attributes": [ { "action": "set", "key": "favorite_actor", "value": "chris_evans", "timestamp": "2019-09-19 12:00:00" }, { "action": "remove", "key": "favorite_color", "timestamp": "2019-09-19 12:00:00" }, { "action": "set", "key": "first_name", "value": "Roger", "timestamp": "2019-09-19 12:00:00" } ] } ``` **Setting two Attributes on a Named User and removing another** ```http POST /api/named_users/my_named_user/attributes HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "attributes": [ { "action": "set", "key": "firstName", "value": "Gyuri", "timestamp": "2020-09-19 12:00:00" }, { "action": "remove", "key": "birthDate", "timestamp": "2020-09-19 12:00:00" }, { "action": "set", "key": "lastName", "value": "Pataki", "timestamp": "2020-09-19 12:00:00" } ] } ``` ## Setting and removing JSON Attributes You can set and remove JSON Attributes on a Channel or a Contact using: * App and Web SDKs * Channels and Named Users APIs ### SDK [iOS SDK 19.3+](/docs/docs/developer/sdk-integration/apple/ios-changelog/#19.3.0) [Android SDK 19.6+](/docs/docs/developer/sdk-integration/android/changelog/#19.6.0) The code examples below show how to set JSON Attributes using the provided methods. #### Android Kotlin ```kotlin Airship.contact.editAttributes { setAttribute( attribute = "attribute_name", instanceId = "instance_id", expiration = Date(), json = jsonMapOf( "key" to "value", "another_key" to "another_value" ) ) } ``` #### iOS Swift ```swift Airship.contact.editAttributes { editor in try! editor.set( json: [ "key": .string("value"), "another_key": .string("another_value") ], attribute: "attribute_name", instanceID: "instance_id", expiration: Date.now ) } ``` **Setting JSON Attributes for Web** ```js const contact = await sdk.contact const editor = await contact.editAttributes() const nowInSeconds = Math.floor(Date.now() / 1000) await editor .set("attribute_name#instance_id", { key: "value", another_key: "another_value", exp: nowInSeconds } ) .apply() ``` ### API Set or remove JSON Attributes using the Channels and Named Users APIs: * [Set or Remove Attributes on Channels](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#modifychannelattributes) * [Set or Remove Attributes on Named Users](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#modifynameduserattributes) Use `set` or `remove` for the `action` value. Set the key value as `#`. Instance IDs: * Can contain letters, numbers, and underscores only * Must begin with a letter * Must end with a letter or number * Are limited to 31 characters maximum * Are case-sensitive For more information, see [JSON Attributes](https://www.airship.com/docs/guides/audience/attributes/about/#json-attributes) in *About Attributes*. In the examples below we are using the Attribute ID `reservations` and instance ID `a001`. **Setting a JSON Attribute on a Channel** ```http POST /api/channels/attributes HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "audience": { "ios_channel": "b31cf3ab-f33e-46ae-b874-782facda2bab" }, "attributes": [ { "action": "set", "key": "reservations#a001", "value": { "flights": [ { "departs": { "port": "PDX", "time": "2023-12-01T05:09:00" }, "arrives": { "port": "LAX", "time": "2023-12-01T07:09:00" } }, { "departs": { "port": "LAX", "time": "2023-12-08T12:30:00" }, "arrives": { "port": "PDX", "time": "2023-12-08T14:45:00" } } ] } } ] } ``` **Setting the four different types of Attributes on a Named User** ```http POST /api/named_users/my_named_user/attributes HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "attributes": [ { "action": "set", "key": "favorite_food", "value": "cake" }, { "action": "set", "key": "age", "value": 35 }, { "action": "set", "key": "birthdate", "value": "1985-07-14T00:00:00" }, { "action": "set", "key": "flights#id123", "value": { "recordID": 123, "flightsInfo": [ { "departureTime": "2024-07-14T12:35:42+08:00", "flightId": "LY205", "destinationAirportCode": "PDX", "originAirportCode": "LAX" }, { "departureTime": "2024-14-14T12:00:00+08:00", "flightId": "LY315", "destinationAirportCode": "LAX", "originAirportCode": "PDX" } ] } } ] } ``` # Targeting your audience using Attributes > Target Attributes using the dashboard or API. Text, Number, and Date Attributes are targeted directly. You specify the Attribute, an operator, and a value to evaluate against. For JSON Attributes, you target specific properties within the JSON schema, not the object as a whole. > **Warning:** To target users based on a unique user ID or other external identifier, do not use Custom Attributes. Instead, target [Named User](https://www.airship.com/docs/reference/glossary/#named_user). ## Targeting in the dashboard You can include Attributes when using the **Target by conditions** and **Target specific users** audience options for messages and experiments. You can also create [Segments](https://www.airship.com/docs/reference/glossary/#segment) instead of having to recreate your audience selections. Both use the same process. Attributes can be combined with other segmentation data, such as events and Tags. For full instructions and usage locations, see [Segments](https://www.airship.com/docs/guides/audience/segmentation/segments/). For details about configuring each Attribute type, see the next sections. When defining your audience, add each Attribute as a condition. In the image below, the Segment includes a Text Attribute targeting users whose favorite food is lasagna. The Attribute name is "Favorite Food", the operator is `Equals`, and the value is `lasagna`. ![Creating a Segment in the dashboard](https://www.airship.com/docs/images/segment-builder_hu_4e1acc92b6780a23.webp) *Creating a Segment in the dashboard* ### Configure Text, Number, and Date Attributes To configure Text and Number Attributes, select an operator, select **Add a value** and enter a value. Select outside the field or hit Enter on your keyboard to save the value. Repeat for multiple values. Multiple values are evaluated as a Boolean OR. To configure Date attributes, select an operator, and then configure a date or range. Availability and requirements depend on the operator. For the *Between* operator, the end date is not inclusive. For example, `Between July 5 - July 17` includes dates July 5 to July 16. Use these configuration steps for Specific, Relative, and Today: | Option | Steps | | --- | --- | | **Specific** | Select a Year/Month/Day. With the _Equals_ and _Does not equal_ operators you can also use the formats Day, Month, Month/Day, and Year/Month. | | **Relative** | Specify the number of years/months/days/hours/minutes from today's date. With the _Equals_ and _Does not equal_ operators, also select Month/Day or Year/Month/Day. | | **Today** | With the _Equals_ operator, select Month/Day or Year/Month/Day. With the _After_ and _Before_ operators, Year/Month/Day is the only option and is preselected. | ### Configure JSON Attributes For JSON Attributes, you target one or more properties in its schema for evaluation. For multiple properties, set Boolean logic to determine whether any or all evaluations must be true for the whole condition to be true. > **Note:** When using the "is not equal to" (!=) operator, the system treats missing information differently based on the Attribute type. For JSON Attributes, if a user doesn't have a value for a specific property, that user is skipped from evaluation. For Text, Number, or Date Attributes, if a user is missing a value for the Attribute, that absence is considered "null", which is evaluated as whether it is not equal to the specified value, which is typically true. > > For example, consider a project with 100 users: > > * Targeting a segment using a JSON Attribute `flight.destination` != `"London"`: Suppose 10 users have values for the property, and one of those users has the value `"London"`. The system will only evaluate the 10 users who explicitly have the property. Of the 10, one is "London", so the condition is true for nine users. The 90 users who do not have the `flight.destination` property are skipped from this evaluation. Result: nine users are included. > > * Targeting a segment using a Text Attribute `singleFlightDestination` != `"London"`: All 100 users are included in the evaluation, even if their `singleFlightDestination` value is missing, because the missing value is treated as `"null"`. If one user has `singleFlightDestination` as `"London"`, then 99 users will satisfy the condition: `"null"` != `"London"` is true, and any other value not equal to `"London"` is also true. Result: 99 users are included. After selecting a JSON Attribute: 1. Select **Configure**. ![Configuring a JSON Attribute in a Segment](https://www.airship.com/docs/images/segment-attribute-json_hu_62babdb749d33e10.webp) *Configuring a JSON Attribute in a Segment* 1. Under **Evaluations**, choose from the **Select a source** menu: | Option | Description | | --- | --- | | **\** | [An alternate name defined for a property.](https://www.airship.com/docs/guides/audience/attributes/adding/#add-json-attributes) The Attribute's schema will appear with the aliased property's line selected. | | **Select from schema** | The Attribute's schema will appear. Select a property's line, then its path will appear to the right of the menu. | 1. (For string and number properties) Select an operator and enter a value. 1. (For Boolean properties) Select **Is true** or **Is false**. 1. (For date properties) Select an operator and configure a date or range. Availability and requirements depend on the operator. For the *Between* operator, the end date is not inclusive. For example, `Between July 5 - July 17` includes dates July 5 to July 16. Use these configuration steps for Specific, Relative, and Today: | Option | Steps | | --- | --- | | **Specific** | Select a Year/Month/Day. With the _Equals_ and _Does not equal_ operators you can also use the format Year/Month. | | **Relative** | Specify the number of years/months/days/hours/minutes from today's date. With the _Equals_ and _Does not equal_ operators, also select Month/Day or Year/Month/Day. | | **Today** | With the _Equals_ operator, select Month/Day or Year/Month/Day. With the _After_ and _Before_ operators, Year/Month/Day is the only option and is preselected. | 1. (Optional for arrays in the path) Select **First** or **Last** to specify the first or last item in the array. Defaults to **Any**. 1. Select the check mark to add the property. 1. Select **Add another** for more properties. 1. (For multiple properties) Select **AND** or **OR** to determine how to evaluate multiple properties within the condition: * AND = all criteria must be met * OR = any criteria must be met 1. Select **Done**. ## Targeting using the API Use the [Attributes audience object](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/) to target any Attribute type. For Text, Number, and Date Attributes, use the Attribute ID as the value for `attribute` and specify a comparison `operator` and Attribute `value`. `precision` is also required for some operators for Date Attributes. For more information, see: * [Text Attributes Selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/#textattribute) * [Number Attributes Selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/#numberattribute) * [Date Attributes Selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/#dateattribute) **Example push targeting a Text Attribute** ```http POST /api/push HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "audience": { "attribute": "item_purchased", "operator": "contains", "value": "jeans" }, "device_types": [ "ios", "android", "web" ], "notification": { "alert": "Hello from Airship" } } ``` **Example push targeting a Date attribute** ```http POST /api/push HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "audience": { "attribute": "account_creation", "operator": "equals", "value": "2023-05-24", "precision": "year_month_day" }, "device_types": [ "web" ], "notification": { "alert": "Hello from Airship" } } ``` Use Boolean `NOT` or `AND` operators to create compound audience expressions. In the following example, the `NOT` operator gives you the same result as if you had used the "Does not contain" operator building a Segment in the dashboard. For more about Boolean audience operators, see [Audience Selection: Compound Selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/#compoundselector) in the Data Formats section of our API reference. **NOT operator** ```json { "NOT": { "attribute": "item_purchased", "operator": "contains", "value": "jeans" } } ``` **AND operator** ```json { "AND": [ { "attribute": "size", "operator": "greater", "value": 12 }, { "attribute": "size", "operator": "less", "value": 15 } ] } ``` For JSON Attributes, the [Attributes audience object](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/) must contain the Attribute ID as the value for `attribute` and a `where` object. The `where` object defines a `property` as a JsonPath expression, the property `value`, a comparison `operator`, and the property type as a `compare_as` value. See [JSON Attributes Selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/#jsonattribute) for more information. **Audience object for a JSON Attribute** ```json { "audience":{ "attribute": "books_on_books", "where":{ "property": "$.x.store.book[*].title", "operator": "equals", "value": "Dracula", "compare_as": "text" } } } ``` For details and more example requests, see [Attributes](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/) in the Data Formats section of our API reference. --- As in the dashboard, you can create reusable Segments instead of having to recreate your audience selections. See [Segments](https://www.airship.com/docs/developer/rest-api/ua/operations/segments/) in our API reference. ## Operators Operators per Attribute type: | Attribute type | Operators | API reference | | --- | --- | --- | | **Text** | equals, contains, less, greater, is_empty | [Text Attribute Selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/#textattribute) | | **Number** | equals, contains, less, greater, is_empty | [Number Attribute Selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/#numberattribute) | | **Date** | equals, before, after, is_empty, range | [Date Attribute Selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/#dateattribute) | | **JSON** | equals, contains, not_contains, less, greater, is_empty, not_empty1 | [JSON Attribute Selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/attributes/#jsonattribute) | 1. If the JsonPath expression maps to an array, the only available operators are is_empty, not_empty, contains, or not_contains. The same operators are available when creating a Segment in the dashboard, but some have slightly different labels, such as "Does not contain" instead of `not_contains`. # Managing Attributes > Edit and archive Attributes and view your upload history. To view a list of your Attributes, go to **Audience**, then **Attributes**. The page opens to **Attribute List**. The default sort order is by last created, and each row displays: * Name — Attributes from [Zero-copy data integration](https://www.airship.com/docs/guides/features/data-integration/zero-copy-data-integration/) are labeled **External**. * Type * ID * Created and modified dates in UTC All Attributes are displayed by default. Your total number of [Custom and Predefined Attributes](https://www.airship.com/docs/guides/audience/attributes/about/#categories-data-sources-and-setup) is displayed next to **Create Attribute**. You can search for specific Attributes by name or ID. You can also filter for Default and Custom Attributes. The Custom filter includes Predefined Attributes. Toggle between **Active** and **Archived** to update the list. Attribute management options: | Option | Description | Steps | | --- | --- | --- | | **Edit** | You can change any active Attributes's name and an active JSON Attribute's schema and aliases. You cannot edit archived Attributes — you must first unarchive it to change its status back to Active. | Select the edit icon ( ), make your changes, then select **Save**. | | **Archive/Unarchive** | Custom and Predefined Attributes only. Archiving reduces the total count of Attributes and stops data collection for an Attribute. Data collected prior to archiving is made available again after unarchiving. Archived Predefined Attributes do not appear in search when [adding Attributes to your project](https://www.airship.com/docs/guides/audience/attributes/adding/). | Select the archive icon ( ). | > **Note:** * [Contact Airship Support](https://support.airship.com/) to delete Custom Attributes. > * You cannot edit or archive Attributes from [Zero-copy data integration](https://www.airship.com/docs/guides/features/data-integration/zero-copy-data-integration/) in the dashboard. To make updates, contact your Airship account manager or Support. ## Viewing upload history To view the history of [Attributes set using a CSV file](https://www.airship.com/docs/guides/audience/attributes/setting/#csv-file), go to **Audience**, then **Attributes**, then **Upload History**. The list also includes [Named User association uploads](https://www.airship.com/docs/guides/audience/named-users/#csv-file). 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.

## Events Events power Airship automation, segmentation, and data products. # Events > Events power Airship automation, segmentation, and data products. Airship SDKs and APIs generate dozens of different kinds of events, ranging in purpose from engagement events like *app opens* or *screen views*, to Airship system events like *sends*, to custom events that you can define to suit your brand's needs. See also the [Events Reference](https://www.airship.com/docs/reference/data-collection/events/). ## What are events? From our friends at [dictionary.com](https://www.dictionary.com/browse/event): **event** [ ih-vent ] _noun_ * something that happens or is regarded as happening; an occurrence, especially one of some importance. * the outcome, issue, or result of anything: *The venture had no successful event.* * something that occurs in a certain place during a particular interval of time. In the Airship system, your business systems, social media, and elsewhere, events happen all the time. People are using your app (or not!), changing location, opting in or out of notifications, and these actions or inactions generate events. Events can represent: - **Customer behavior** — App open, pageview, purchase - **Airship system activity** — Compliance, message sends, message expiration - **External events** — Social media, POS transactions, CRM changes ## What can I do with events? Events power our internal data products, partner integrations, and automation and segmentation services. They are also emitted into the Airship [Real-Time Data Streaming (RTDS)](https://www.airship.com/docs/reference/glossary/#rtds) service, allowing you to use streaming event data for custom integrations. To learn more about how to leverage Airship events, see the following resources: - [Event Segmentation](#event-segmentation) — Segment audiences by event count, value, and recency, and with advanced filtering capabilities. - [Automation and Sequences](https://www.airship.com/docs/guides/messaging/messages/sequences/) — Trigger messages based on events and event properties. See also [In-App Automation](https://www.airship.com/docs/reference/glossary/#iaa) and [Scenes](https://www.airship.com/docs/reference/glossary/#scene). - [Data & Analytics](https://www.airship.com/docs/guides/audience/) — Analyze customer trends and optimize your engagement strategy with our data products: Real-Time Data Streaming and [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa). - [Integrations](https://www.airship.com/docs/integrations/) — Gain a broader understanding of the customer lifecycle, from attribution to acquisition to engagement, with one of our ready-made partner integrations. ## What do events look like? Events typically include a timestamp for when the event occurred, information about the associated user and/or device, the event `TYPE`, and additional user- or event-specific details. Here's an example of a `SCREEN_VIEWED` event as it appears in the RTDS stream: ```json { "id": "fe882bd1-e0b9-11ea-bc35-0242f70dd9ff", "offset": "1000060042216", "occurred": "2020-08-17T18:46:28.046Z", "processed": "2020-08-17T18:46:44.405Z", "device": { "ios_channel": "e27dd2e0-62e8-44e1-b123-2a98f6dd873e", "channel": "e27dd2e0-62e8-44e1-b123-2a98f6dd873e", "device_type": "IOS", "named_user_id": "pfd", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "false", "session_id": "261371DB-235A-45DE-B1F2-A6B92507BCD3", "GA_CID": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d", "com.urbanairship.idfa": "00000000-0000-0000-0000-000000000000", "com.urbanairship.vendor": "164594EF-582D-4F1D-B1B8-844738591F86" }, "attributes": { "locale_variant": "", "app_version": "738", "device_model": "iPhone12,8", "app_package_name": "com.urbanairship.stag.goat", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "13.5.1", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "true", "background_push_enabled": "true", "ua_sdk_version": "14.0.0-beta1", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "duration": 80799213, "viewed_screen": "home", "session_id": "c7adcd61-47c3-412f-9a60-e626ab4c3d1a" }, "type": "SCREEN_VIEWED" } ``` ## Event types Many events are available out of the box for segmentation. Others require configuration in your SDK implementation and by activating them in the Airship dashboard. We classify events as one of: default, predefined, or custom. Properties associated with the events can be used for [filtering events](#filtering) used in automation and segmentation. Default events : Default events, aka *out-of-the-box* events, are standard to every implementation, and are automatically enabled for segmentation. Common default events include *app open* and *web click*. Default events have properties assigned by Airship. Custom events : Custom events are events for which you define your own name and custom properties. Custom events support a numeric *value* field which can hold values such as purchase price or a percentage of content consumed. Track custom events from our SDKs or associate them directly with a user using our [Custom Events API](https://www.airship.com/docs/developer/rest-api/ua/operations/custom-events/). Once you define a custom event, you must [activate the event for segmentation](https://www.airship.com/docs/guides/audience/events/manage/) in the dashboard. Predefined events : Predefined events are custom events that are built into our SDKs as [Custom Event Templates](https://www.airship.com/docs/sdk-topics/custom-events/). Predefined events represent many common customer use cases for retail-, account-, and media-related events, such as *registered account* or *shared content*. Predefined events must be [activated for segmentation](https://www.airship.com/docs/guides/audience/events/manage/) in the dashboard. Predefined events have properties assigned by Airship, but you can modify or remove them, and you can add your own. Below is a table showing which events require additional configuration for segmentation. | [Event](#events) | Predefined properties | Enabled for segmentation by default | |-------------------|------------|------------------------------------------| | Default (Out-of-the-box) | :white_check_mark: | :white_check_mark: | | Custom | :x: | :x: | | Predefined (built-in) | :white_check_mark:1 | :x: | 1. Can be modified, added, and removed. See the [Events Reference](https://www.airship.com/docs/reference/data-collection/events/) for activity names and property information for default, predefined, and custom events. ### Default events Default (OOTB) events come standard with any implementation of our SDKs, or in the case of SMS and email, our channels APIs. Default events correlate with [RTDS events](https://www.airship.com/docs/developer/rest-api/connect/schemas/events/), but for the purposes of segmentation, see our [Events Reference](https://www.airship.com/docs/reference/data-collection/events/), as event types and names may differ slightly. For example, in RTDS, an *email unsubscribe* event has a `type` of `COMPLIANCE`, an `event_type` of `registration`, and a `registration_type` of `unsubscribe`. **Email unsubscribe event in RTDS** ```json { "id": "bd8c90d6-5704-4438-8075-7530d06c4cba", "offset": "1000001778792", "occurred": "2018-11-27T23:47:54.641Z", "processed": "2018-11-27T23:47:55.516Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "former.user@example.com" }, "body": { "event_type": "registration", "properties": { "message_type": "commercial", "registration_type": "unsubscribe" } }, "type": "COMPLIANCE" } ``` When targeting an audience after an email unsubscribe event, however, you will use the `activity` name of `email_unsubscribe` in your request. **Target a segment of users based on an email unsubscribe event** ```json { "audience": { "activity": "email_unsubscribe", "metric": "count", "operator": "equals", "value": 1 }, "notification": { "email": { "subject": "Sorry to see you go!", "html_body": "

We received your unsubscribe request.

Hope you come back some day!

" }, "device_types": [ "email" ] } ``` In the dashboard, you can create this audience when building a [Segment](https://www.airship.com/docs/reference/glossary/#segment) or targeting a specific audience: 1. Search for and select the `email_unsubscribe` event. 1. Select *Performed event*. 1. Select the *Equals* operator and enter the value `1`. ![Targeting users by email unsubscribe event](https://www.airship.com/docs/images/segment-email-unsub_hu_3cca8f780c3e731e.webp) *Targeting users by email unsubscribe event* ### Predefined events Predefined events are `CUSTOM` events, and are available to use out-of-the-box with built-in templates in our iOS, Android, and Web SDKs. Predefined event are available for many common retail-, media- and account-related use cases. The properties for these events are also predefined, but you can edit or remove them and also add custom properties. See: [Manage Events](https://www.airship.com/docs/guides/audience/events/manage/). You must implement and track the events in your app or website using [Custom Event Templates](https://www.airship.com/docs/sdk-topics/custom-events/). The following example uses the retail template in our Web SDK to create and track a `purchased` event, passing in optional properties. ```js new sdk.CustomEvent.templates.retail.PurchasedEvent(99.99, { id: "12345", category: "mens shoes", description: "Low top", brand: "SpecialBrand", new_item: true, }, "13579").track() ``` Adding and tracking events in the SDK, however, does not activate them for segmentation. See [Manage Events](https://www.airship.com/docs/guides/audience/events/manage/) to learn how to activate predefined events in the dashboard. ### Custom events If predefined events don't meet your requirements, you can create and track your own custom events in our SDKs, or submit events with our [Custom Events API](https://www.airship.com/docs/developer/rest-api/ua/operations/custom-events/). Unlike predefined events, you must define your own event name and properties. Custom events will appear in RTDS and Performance Analytics under the `name` that you define for the event. As with predefined events, you must activate your custom event in the UI for segmentation. **Example custom event** ```json { "id": "036ea86a-4336-40c5-80af-27c4d30fb3d1", "offset": "1000060042791", "occurred": "2020-08-18T04:52:00.000Z", "processed": "2020-08-18T04:52:04.695Z", "device": { "channel": "aafe7a54-e1f6-463e-8821-3ccfedf0cf3c", "device_type": "WEB", "named_user_id": "ivan_ivanovich" }, "body": { "name": "my_event", "interaction_type": "url", "interaction_id": "https://example.com", "value": 20, "session_id": "774afcd9-c5dd-47bf-94c9-a4f209d49f4a", "source": "SDK", "properties": { "mood": "happy", "value": 55 } }, "type": "CUSTOM" } ``` Custom events will have a `type` of `custom` and can represent any user action you wish to track in the SDK. You can also add events that are unrelated to an Airship app or site by using the API. To learn more about custom events, see our [Custom Events Guide](https://www.airship.com/docs/guides/audience/events/custom-events/). ## Event segmentation You can target your message and experiment audiences using events. Example audience targeting: * Users who opened your app three times in the past seven days * Users who opened your app in the past six weeks * Users who were sent an SMS six times in the last two weeks * Users who made a purchase of more than $100 in the last 15 days * Users who have not viewed more than five pieces of content Using the API, see the [Segments endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/segments/). See also the [Event Segmentation schema](https://www.airship.com/docs/developer/rest-api/ua/schemas/event-segmentation/). In the dashboard, you can include events when using the **Target by conditions** and **Target specific users** audience options for messages and experiments. You can also create [Segments](https://www.airship.com/docs/reference/glossary/#segment) instead of having to recreate your audience selections. Both use the same process. Events can be combined with other segmentation data, such as Attributes and Tags. For full instructions and usage locations, see [Segments](https://www.airship.com/docs/guides/audience/segmentation/segments/). Details about configuring event conditions, see the next section. When defining your audience, add each event as a condition, choose whether or not the event was performed, and set the frequency of occurrence. You can also specify a date or range when the event occurred and filter by properties associated with the event. To configure event conditions: 1. Select **Performed event**, **First performed event**, **Last performed event**, or **Did not perform event**. 1. (For *Performed event* and *Did not perform event* only) Select the *Equals* or *Between* operator and configure the frequency of the event. 1. (Optional) Select **Specify when** to target when the event was performed, then select an operator and configure a date or range. Availability and requirements depend on the operator. * **Specific** — Select a Year/Month/Day. With the *Equals* operator you can also use formats Month/Day, and Year/Month. * **Relative** — Specify the number of years/months/days/hours/minutes from today's date. With the *Equals* operator, also select Month/Day or Year/Month/Day. * **Today** — Select Month/Day or Year/Month/Day. > **Note:** For the *Between* operator, the end date is not inclusive, e.g., selection `Between July 5 - July 17` includes dates July 5 to July 16. 1. (Optional) Filter events using numeric values associated with the events or by key/value properties attached to the events. Filtering events this way can help you more precisely target your audience. 1. Select **Add Property** and search for a property, or select **Add Event Value**. 1. If applicable, select the operator you want to use to evaluate the value or property. 1. Enter a value, then select outside the field or hit Enter on your keyboard to save the value. Repeat for multiple values. Multiple values are evaluated as a boolean OR. 1. (Optional) Select **Add Property** or **Add Event Value** to add more filters. 1. Select *AND/OR* to determine how to evaluate multiple filters and alternatives within each filter. * **AND** = all criteria must be met * **OR** = any criteria must be met > **Note:** Properties of type "Array" may have [multiple values defined for the same sub-property](https://www.airship.com/docs/guides/audience/events/manage/#create-a-new-event). When segmenting with array sub-properties that can hold multiple values, be aware that the evaluation of AND and OR conditions can be complex. Ensure your boolean logic precisely matches how you intend to filter based on these potentially multiple values within a single sub-property. This example shows a segment that targets users with the `purchased` event occurring twice between the dates September 1, 2020, and September 15, 2020: ![Targeting users by event count and date range](https://www.airship.com/docs/images/segment-builder-events_hu_ae0c1718df86005a.webp) *Targeting users by event count and date range* ### Segment evaluation Airship uses a 90-day "look back" for events and event properties used in segmentation. The exception is for "first" and "last" occurrences, which are stored even if they are more than 90 days old. This window (and the storage of first/last occurrences) starts when an event is [activated for segmentation](https://www.airship.com/docs/guides/audience/events/manage/). As of January 2023, “last performed” occurrences are included when evaluating segmentation queries **for events without properties**, even when not using the "last performed" operator. For example, prior to this change, if you targeted all users who performed the event `added_to_cart` one or more times, **only** users who performed the event one or more times in the last 90 days were included in the target audience. With the change, users who performed the event one or more times in the last 90 days **AND** users who "last performed" the event prior to the 90-day period would be included in the target audience. If the query includes a property, such as "added to cart 1 or more times, where the category = shoes," the evaluation does not include “last performed” occurrences. ### Filtering by event properties {#filtering} In addition to targeting your audience by event count, value, and recency, you may further refine your selection by filtering on event properties. To target event properties, use the [where object](https://www.airship.com/docs/developer/rest-api/ua/schemas/event-segmentation/#whereobject) in the API, and include the path to the property along with the values you are filtering for, e.g., push ID, email address, or campaign category. In the example below, the audience is users who have opened the app by tapping a push notification with the `push_id` of `"28e9d533-c8a7-4abf-93f4-4794b09391eb"`: ```json { "audience": { "activity": "app_open", "value": 0, "operator": "greater", "metric": "count", "where": { "property": "/_triggering_push/push_id", "operator": "equals", "compare_as": "text", "value": "28e9d533-c8a7-4abf-93f4-4794b09391eb" } } } ``` In the dashboard, you can create this audience in a condition: 1. Add the `app_open` event. 1. Select **Performed event**. 1. Select the *Greater than* operator and enter the value `0`. 1. Select **Add Property**. 1. Search for and select `/_triggering_push/push_id`. 1. Select the *Equals* operator and enter the value `28e9d533-c8a7-4abf-93f4-4794b09391eb`. ![Filtering by push ID in a Segment](https://www.airship.com/docs/images/segment-push-id_hu_fa6643da2f326d3a.webp) *Filtering by push ID in a Segment* # Custom Events > Track user activity and conversions in your Airship channels, submit external events to Airship, trigger messages and sequences, and segment your audience with custom events. ## Overview Custom events extend our [default events](https://www.airship.com/docs/guides/audience/events/events/). Such events as *opens* or *tag change* are applicable to all apps and websites. Custom events, on the other hand, are specific to the needs of your app or website. For example, you may be interested in tracking the *order created* event in your e-commerce app, the *playback started* event in your content delivery platform, or the *OnParticipatedInExperimentNotification* event in your A/B testing application for tracking user participation. You may track custom events either via our mobile and web SDKs or by using any other event tracking system. In this guide, we will show you how to tie your digital engagement activities together using custom events: Set up via templates or directly in code : Setting up a custom event for your app is easy. For common event types, we provide ready-made templates in our [Mobile and Web](https://www.airship.com/docs/sdk-topics/custom-events/) SDKs. Alternatively, you can set up custom events directly in your code by instantiating a class from the SDK that implements the custom event API and passing a string that represents the name of the event. Extend with properties : To provide more detail and customization to the events you are tracking, you may make use of event properties. These are key/value pairs, where the key represents the name of a property and the value is the information associated with this property. Examples of event properties are *a product SKU on a purchase event*, or *a category on a viewed video event*. Stream in real time : Our *Real-Time Data Streaming* supports streaming custom events to your business systems in real time. See our [Data Streaming API Reference](https://www.airship.com/docs/developer/rest-api/connect/schemas/events/#custom) for details. Trigger automation or sequence : You may set up custom events and their properties to trigger an automation or sequence: members of your audience may receive personalized messages with [Dynamic Content](https://www.airship.com/docs/reference/glossary/#dynamic_content) that includes information from the custom event. For example, if your custom event has a `user_name` property, you can add `{{user_name}}` to your message, and anybody receiving the message would see their *user name* — the value of the `user_name` property. ## Emitting Custom Events from Message Actions You can emit custom events when users interact with [Scenes](https://www.airship.com/docs/reference/glossary/#scene), [push notifications](https://www.airship.com/docs/reference/glossary/#push_notification), or [in-app messages](https://www.airship.com/docs/reference/glossary/#in_app_message). This allows you to track user interactions with specific message elements without implementing SDK code. **Scenes** — Emit an event when a user taps a button, image, or screen. See [Emit a Custom Event](https://www.airship.com/docs/guides/messaging/in-app-experiences/configuration/button-actions/#emit-a-custom-event) in *Actions* for Scenes. **Push notifications and in-app messages** (iOS SDK 20+) (Android SDK 20+) — Emit an event when a user taps the message or a button within the message. See: * [Creating content](https://www.airship.com/docs/guides/messaging/messages/content/app/push-notifications/#creating-content) in *Push Notification Content* * [Creating content](https://www.airship.com/docs/guides/messaging/messages/content/app/in-app-messages/#creating-content) in *In-App Message Content* * [Add buttons to message content](https://www.airship.com/docs/guides/messaging/messages/buttons/#add-buttons-to-message-content) in *Buttons* To emit Custom Events from the API, use the [add_custom_event](https://www.airship.com/docs/developer/rest-api/ua/schemas/push/#actionsobject) notification action. ## Tracking Custom Events We recommend starting by identifying a few most important actions that users perform in your app or site. These could include: * Registering for an account * Using a new feature * Watching a video * Viewing a specific screen * Saving or sharing content * Adding a product to a list or cart * Making a purchase Custom events track *actions* and not *objects*. For this reason, a good practice is to apply the *verb-first* naming convention to custom events. You can also track these events in varying levels of detail, based on how you name them, and optionally include values with each event. You may have other systems that track the granular specifics of your e-commerce engine or content consumption. To measure the impact of push, consider keeping reports at a higher level when starting out. For example, as a publisher, you could track a purchase event in a few ways: * Purchased a Magazine * Purchased a Sports Magazine * Purchased *Sports Illustrated*, Volume 17, Issue 9 While the third variation above might provide the most detail, you can start with the first level of granularity to keep your reports easy to digest and roll-up, and still see which push notifications were driving the most engagement or ROI. Here are some examples in more detail: > **Tip:** In our examples below, event names are lowercased. We use dashes to separate levels of granularity, and underscores > for multi-word names/values. > For example: > > * event_name-event_category > * purchased_item-sports_magazine | Market vertical | Description | Example event name | Event value | | --- | --- | --- | --- | | All | User registers for an account | registered_account | | All | User stars any product, article, or content | starred_content | | Media | User browses a category articles or content | browsed_content | | Media | User plays a video *Could use the event value to set the amount of time spent watching the video. Report the event after the user navigates away from the video or stops the video.* | consumed_content | Percentage of content consumed | | Media | User shares content | shared_content | | Retail | User adds item to cart | added_to_cart | | Retail | User purchases an item *Use event value to capture the value of the item* | purchased | Purchase Price | We provide ready-made templates for our mobile and web SDKs to get you started with a number of common account-, media-, and retail-related events. See the templates in our [Custom Events](https://www.airship.com/docs/sdk-topics/custom-events/) SDK documentation. With our mobile and web SDKs, tracking custom events is similar to [adding an Airship segmentation tag](https://www.airship.com/docs/developer/sdk-integration/web/segmentation/). Set specific properties and assign a range of values that must be met in order to trigger automation rules. Custom event properties can contain objects and arrays of objects. Use dot notation to access nested properties: `parent_property.child_property`. * API: [Custom Event Selectors](https://www.airship.com/docs/developer/rest-api/ua/schemas/pipeline-objects/#eventidentifier) * Dashboard: [Manage Events](https://www.airship.com/docs/guides/audience/events/manage/) > **Note:** Custom event properties used to be referenced in the `$data.events.[0].properties` namespace. If you have templates referencing properties in this namespace, they'll still work, but you'll have to continue using this namespace until you [contact Airship Support](https://support.airship.com/) and move over to the simplified namespace for custom event properties. To minimize battery consumption, custom events are automatically combined and sent batched in the background. For more information, see [Tips and Code Samples](#tips-and-code-samples). Simple example : Here is a simple example that demonstrates how to track a custom event named **consumed_content**: **iOS** ```swift var event = CustomEvent(name: "consumed_content", value: 123.12) // Set custom event properties event.setProperty(bool: true, forKey: "boolean_property") event.setProperty(string: "string_value", forKey: "string_property") event.setProperty(double: 11.0, forKey: "number_property") // Record the event in analytics event.track() ``` **Android** ```java // Create and name an event Builder builder = CustomEvent.newBuilder("consumed_content"); // Set custom event properties on the builder builder.addProperty("bool_property", true); builder.addProperty("string_property", "string_property_value"); builder.addProperty("int_property", 11); builder.addProperty("double_property", 11.0d); builder.addProperty("long_property", 11L); ArrayList collection = new ArrayList(); collection.add("string_array_value_1"); collection.add("string_array_value_2"); collection.add("string_array_value_3"); builder.addProperty("collection_property", JsonValue.wrapOpt(collection)); CustomEvent event = builder.build(); // Start tracking the event event.track(); ``` **Web** ```js // Create and name an event var event = new sdk.CustomEvent("consumed_content") // Start tracking the event event.track() ``` Assigning a value to a custom event : In this example, you will create an event with a value for advanced analytics reporting: **iOS** ```swift // Create and name an event with a value let event = CustomEvent(name: "event_name" value: 123.12) // Track the event event.track() ``` **Android** ```java // Create and track a custom event with a value CustomEvent.newBuilder("event_name") .setEventValue(123.12) .build() .track(); ``` **Web** ```js // Create and name an event with a value var event = new sdk.CustomEvent('event_name', 123.12) // Start tracking the event event.track() ``` ## Server-Side Events Server-side events are sent through the [Custom Events API](https://www.airship.com/docs/developer/rest-api/ua/operations/custom-events/). When you submit an event, you'll provide the [channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) or [Named User ID](https://www.airship.com/docs/reference/glossary/#named_user) of the user you want to associate the event with. You can use [Event identifiers](https://www.airship.com/docs/developer/rest-api/ua/schemas/pipeline-objects/#eventidentifier) to send automated messages to the *channel ID* or *named user* associated with each event. Attributing events to named users can help you better represent user actions and trigger automations for individual users without having to map channels to external IDs. Server-side events are involved in a significant number of Airship integrations. > **Note:** [Server-side events](https://www.airship.com/docs/guides/audience/events/custom-events/#server-side-events) cannot be used to trigger an [In-App Automation](https://www.airship.com/docs/reference/glossary/#iaa) or [Scene](https://www.airship.com/docs/reference/glossary/#scene). > > Custom Events used for In-App Automation or Scene triggers must be client-side events. Web Scenes can only use Custom Events tracked using the Web SDK. App Scenes and In-App Automations can only use Custom Events tracked using the Mobile SDK. **Sample Custom Event** ```json [ { "occurred": "2016-05-02T02:31:22", "user": { "named_user_id": "hugh.manbeing" }, "body": { "name": "purchased", "value": 239.85, "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a", "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234", "interaction_type": "url", "properties": { "description": "Sneaker purchase", "brand": "Victory Sneakers", "colors": [ "red", "blue" ], "items": [ { "text": "New Line Sneakers", "price": "$ 79.95" }, { "text": "Old Line Sneakers", "price": "$ 79.95" }, { "text": "Blue Line Sneakers", "price": "$ 79.95" } ], "name": "Hugh Manbeing", "userLocation": { "state": "CO", "zip": "80202" } }, "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1" } } ] ``` ## Custom Events vs. Audience Segmentation Tags Custom events are similar to [audience segmentation tags](https://www.airship.com/docs/developer/sdk-integration/web/segmentation/). While tags target users via audience segmentation, custom events inform analytics reporting and trigger automated messages. For example, a user can be tagged as a *purchaser* after making a purchase. This user can be segmented later for sending follow-up messages. You may use a custom event to track when the user *purchased shoes*. This is something that happened, and you may wish to calculate its business impact across all users. Audience tags are useful to identify users for future campaigns. A person who has purchased before may be receptive to a different type of future messaging. A tag only tells you that this user purchased at least once. Because it is useful to understand how many purchases are made in total during a period of time, we have custom events so you can keep track of both types of data. ## Event Reporting Once you have the latest SDK installed and a snippet of code tracking custom events, you'll start to see event data show up in your message reports. These events will appear in each message report, and in an aggregate app report, with information on whether each event occurred on an Airship delivery channel (Landing Page or Message Center), or in a custom location in your app or website. These reports display summary data, and a CSV export option will provide full data that you can manipulate as needed or import into business intelligence or analytics tools. See [View Attributed Events](https://www.airship.com/docs/guides/reports/message/#view-attributed-events) in *Message Reports* and [Scene Detail](https://www.airship.com/docs/guides/messaging/in-app-experiences/scenes/create/scene-reports/#scene-detail) in *Scene Reports*. ## Push Attribution Because Airship has visibility into both the sending and receiving (via SDK) of each push, our Push Attribution model ties these custom events back to each message so that you can see the full story of conversions following both direct and indirect opens. We track how each custom event is attributed to a specific push. The following options are available: * Direct Attribution of Events * Indirect Attribution of Events * Unattributed Events Direct attribution : If a push notification is sent to a device and the user taps on the notification to open the app and complete a custom event, then the event will be recorded with the **Direct** attribution to that push notification. Indirect attribution : If a push notification is sent to the device and the user does not tap on the notification, but opens the app later that day (within a 12 hour *attribution window*) and completes a custom event it will be recorded with **Indirect** attribution to that push notification. If the event is completed after 12 outside of the attribution window, then the event will be categorized as **Unattributed**. Unattributed events : If a user completes a custom event during a time when no push was sent, or that user is opted-out, then the event will be categorized as **Unattributed**. ![Custom Event push attribution flowchart](https://www.airship.com/docs/images/custom_events_flowchart_hu_dc4de354521cbfdf.webp) *Custom Event push attribution flowchart* ## Tips and Code Samples When setting up custom events, remember: * Start by tracking two to five key activities or conversion points in your app. * When naming events, keep the total number of unique event names reasonable, so your reports are easy to read. * Event will be ignored if their names contain more than 255 characters. * Use consistent naming conventions for your events. We lowercase all incoming events for consistency in reports. * Event Values must be between -231 and [231 - 1] or the value will be ignored. * Event Values cannot contain `$` or `,` characters or the value will be ignored (decimals only). ### JavaScript for Rich Pages Send a [Message Center page](https://www.airship.com/docs/guides/features/messaging/message-center/) or [landing page](https://www.airship.com/docs/guides/features/messaging/landing-pages/) with the following HTML to set a custom event on the button. In the example below, we create a button (named *buy-button*) which fires the "bought book" event with a value of `10.99`. ```html Store
``` Our example detects if a page is a landing page, sets the `interaction_type` and `interaction_id` if needed, emits an event to the Custom Events system, and writes debugging information to the DOM. Under the hood, a *landing page* is simply a web view, so in order to propagate the knowledge that the event was fired from a landing page to the custom events system, we must set the `interaction_type` to `ua_landing_page` and the `interaction_id` to the URL of the landing page. For a [Message Center page](https://www.airship.com/docs/guides/features/messaging/message-center/), the Airship SDK is able to detect that the event is fired from a Message Center page so `interaction_type` and the `interaction_id` will be taken care of by the SDK. ### Injecting the Airship JavaScript Interface If you have a WebView that exists outside of a Message Center, you can use the following examples to inject the Airship JavaScript interface in to your WebView to enable sending custom events. > **Important:** The Airship JavaScript interface runs Airship actions and > exposes information about the application. It should only be loaded in WebViews > that are displaying content from trusted sources and that only link to other > trusted sources. #### iOS Example The Airship JavaScript interface can be added to any `WKWebView` whose navigation delegate is an instance of [NativeBridge](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/nativebridge) . Custom WebViews can also implement the [NativeBridgeExtensionDelegate](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/nativebridgeextensiondelegate) to extend the JavaScript environment or respond to SDK-defined JavaScript commands. ```swift self.nativeBridge = NativeBridge() self.nativeBridge.nativeBridgeExtensionDelegate = self.nativeBridgeExtension self.nativeBridge.forwardNavigationDelegate = self webView.navigationDelegate = self.nativeBridge ``` Optionally, enable `UAirship.close()` by having the controller implement the `close` method in the `NativeBridgeDelegate` protocol: ```swift func close() { // Close the current window } ``` #### Allowlist Rules For iOS, the [URLAllowList](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/airshipurlallowlist) controls which URLs the Airship SDK is able to act on. As of SDK 17, all URLs are allowed by default. See: [iOS: Configuring Airship](https://www.airship.com/docs/developer/sdk-integration/apple/installation/advanced-integration/#url-allowlist). #### Android and Fire OS example The Airship JavaScript interface can be added to any web view as long as JavaScript is enabled and the client is set to an instance of UAWebViewClient. ```java webView.getSettings().setJavaScriptEnabled(true); webView.setWebViewClient(new UAWebViewClient()) ``` #### Allowlist Rules For Android, the [UrlAllowList](https://www.airship.com/docs/reference/libraries/android-kotlin/latest/urbanairship-core/com.urbanairship/-url-allow-list) controls which URLs the Airship SDK is able to act on. As of SDK 17, all URLs are allowed by default. See: [URL Allowlist](https://www.airship.com/docs/developer/sdk-integration/android/installation/advanced-integration/#url-allowlist). # Manage Events > Configure events and event properties for segmentation, automation, and Goals. [Custom Events](https://www.airship.com/docs/reference/glossary/#custom_event) can contain properties that you have defined outside of Airship. To make these events and their properties accessible to our segmentation and automation services, add them to your project to enable use with these features: * [Custom Event Triggers](https://www.airship.com/docs/reference/glossary/#custom_event_trigger) in Automations and Sequences — See Custom Event in [*Automation triggers*](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#custom-event) and [*Sequence triggers*](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#custom-event). * [Custom Event Triggers](https://www.airship.com/docs/reference/glossary/#custom_event_iaa_trigger) for In-App Automations and Scenes — See [Custom Event](https://www.airship.com/docs/guides/messaging/in-app-experiences/configuration/triggers/#custom-event) in *In-app experience triggers*. * [Cancellation Events](https://www.airship.com/docs/reference/glossary/#cancellation_events_event_option) * Emitting a Custom Event when a user clicks/taps a button, image, or screen in a Scene — See [Emit a Custom Event](https://www.airship.com/docs/guides/messaging/in-app-experiences/configuration/button-actions/#emit-a-custom-event) in *Actions* for In-app Experiences. * [Goals](https://www.airship.com/docs/reference/glossary/#goals) When adding events to your project, you have the option to activate them for event segmentation. See [Event Segmentation](https://www.airship.com/docs/guides/audience/events/events/#event-segmentation) for details on event types and properties. See also [Holdout Experiments](https://www.airship.com/docs/reference/glossary/#holdout_experiment). ## Create a new event Add a new custom or predefined event to your project. 1. Next to your project name, select the dropdown menu (▼), then **Settings**. 1. Under **Project settings**, select **Events**. 1. Select **Create event**. 1. ![Creating a new event](https://www.airship.com/docs/images/create-event_hu_e45f094c012bf9d0.webp) *Creating a new event* Enter a name for your new custom event or search for a predefined event to activate. Predefined events have reserved names and will appear in search results with a `Predefined event` flag. For a list of available predefined events, see [Predefined events](https://www.airship.com/docs/reference/data-collection/events/#predefined-events) in the *Events Reference*. If you choose one of the predefined events, the event properties will be populated for you. If you are creating a new custom event that is unknown to Airship, select **Create custom "[search term]" event** to create it. 1. (Optional) Enter a description for the event. 1. Select an event category or select **Create category** and enter a category name. > **Note:** When Airship adds a new default category that matches a custom category, the default category will replace the custom one. For example, if Airship adds a default "Shipped" category, it will replace your custom "Shipment sent" category, and "Shipment sent" will be removed from your project. 1. (Optional) Check the box to **Activate for segmentation**. 1. (Optional) Add event properties. Predefined events are already populated with properties, and you can add more. You can also edit or remove properties for predefined events. Select **Add property**, then enter a property name and select its type: String, Number, Boolean, Date, Array, or Any. The type determines which operators are available to you when using event segmentation. Select **Any** if the value for the property is unknown or if it could be multiple types. Select **Add another** and repeat to assign additional properties for the event. > **Note:** Properties of type "Any" cannot be used for segmentation. They will not appear in the dashboard when building Segments or targeting using segmentation data, and they cannot be referenced using the API. > > Similarly, properties of type "Array" have these restrictions by default. However, you can make the contents of an array accessible for segmentation by defining their nested properties. See [Defining nested array properties](#defining-nested-array-properties) below. 1. Select **Save**. ### Defining nested array properties When adding an "Array" type property for an event, you can make the contents of the array accessible for segmentation by defining its nested properties using JSON Path expressions. After adding the array property, add sub-properties using the syntax `$.arrayproperty[*].subproperty`. The asterisk (`*`) acts as a wildcard, indicating that the path should match the sub-property for any item within the array property. This makes it possible to segment your audience based on the characteristics of individual items within an array without needing to refer to their specific locations. For example, consider a `Products` array where each product object has a name and price: ```json { "Products": [ { "name": "Laptop", "price": 1200 }, { "name": "Mouse", "price": 25 } ] } ``` To enable segmentation on the name and price of individual products within the `Products` array, you would define the following properties for the event in your project: * `Products` of type Array, to acknowledge the array itself * `$.Products[*].name` of type String, for segmentation using the name of any product in the array * `$.Products[*].price` of type Number, for segmentation using the price of any product in the array ![Specifying properties within an array property](https://www.airship.com/docs/images/array-properties_hu_15ee5a438cc14552.webp) *Specifying properties within an array property* ## Edit or delete events Deleted events or event properties will no longer be available for use in segmentation. If you change an event's name, only the new name will be available for use in segmentation. Similarly, deleted event properties will no longer be available for selection when configuring Automation and Sequence triggers. However, the event itself will still remain available for triggers. 1. Next to your project name, select the dropdown menu (▼), then **Settings**. 1. Under **Project settings**, select **Events**. The table includes a maximum of 1,000 events. 1. Search for an event, and select the more menu icon (⋯) for its row, and then **Delete** or **Edit**. ## Segmentation Build a custom audience of users who share some criteria for message targeting, experiments, and trigger conditions. # Segmenting your audience > Build a custom audience of users who share some criteria for message targeting, experiments, and trigger conditions. While some messages may require broadcasting to all users, typically you want to target a specific audience. The same applies to message A/B test and Feature Flag audiences. Here are a few common scenarios and the target for each: * **App upgrade** — Send an announcement about a new app version and encourage users to upgrade. *Target: App version* * **External user list** — Send messages to a list of users created from your CRM data. *Target: Uploaded List* * **Re-engagement prompt** — Send a re-engagement message based on users' likelihood to stop using your app or website. *Target: [Predicted to Churn](https://www.airship.com/docs/reference/glossary/#predicted_to_churn) risk profile* * **Localized content** — Display different in-app messages based on your users' language and country settings. *Target: Locale* ## Building audience groups When defining audiences using the **Target by conditions** or **Target specific users** options, you can select data to include, such as: * [Attributes](https://www.airship.com/docs/reference/glossary/#attributes) * [Lifecycle List](https://www.airship.com/docs/reference/glossary/#lifecycle_list) * [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) * [Device Properties](https://www.airship.com/docs/reference/glossary/#device_properties) * [Events](https://www.airship.com/docs/reference/glossary/#events) * [Named User](https://www.airship.com/docs/reference/glossary/#named_user) To build the audience, you add *conditions* organized in *blocks*, or select a saved Segment. The procedure is the same. Build the audience by adding *conditions* organized in *blocks*. A block contains one or more conditions, providing a way to mix and match boolean operators. For example, you might use an OR operator for conditions in a block, and use an AND operator to join the blocks together. ![Targeting specific users in the dashboard](https://www.airship.com/docs/images/segment-builder_hu_4e1acc92b6780a23.webp) *Targeting specific users in the dashboard* ### Segments To save a defined audience group for reuse within your project, create a [Segment](https://www.airship.com/docs/reference/glossary/#segment). You can then select that Segment when using **Target by conditions** or **Target Specific Users**. The same interface and procedure apply to both targeting specific users and creating Segments. You can also include any saved Segment within another Segment. See the full procedure in [Segments](https://www.airship.com/docs/guides/audience/segmentation/segments/). To create Segments using the API, see the [`/api/segments` endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/segments/). To target specific users using the API, use the `"audience"` object. See the [Audience Selection API schema](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/). ### Channel-level filtering After building an audience group to target specific users or in a Segment, you can filter messages to specific channels at the message composition stage using Channel Conditions. For example, to send to only devices that have language set as English, add a channel condition for `{ua_language=EN}`. ### Client-side vs server-side data {#client-server} Airship client-side data mostly comes from [apps and websites that use our SDK](https://www.airship.com/docs/guides/reports/reports/#engagement-data). This is the source of *client-side* data used for targeting. Client-side data includes [Device Properties](https://www.airship.com/docs/reference/glossary/#device_properties) and [Attributes](https://www.airship.com/docs/reference/glossary/#attributes). See reference: [Default Attributes](https://www.airship.com/docs/reference/data-collection/attributes/#default-attributes). You can also group users and add Attributes and Tags yourself — this is considered *server-side* data. CRM and POS systems are common sources. For segmentation, you can create: * [Attributes](https://www.airship.com/docs/reference/glossary/#attributes) * [Audience Lists](https://www.airship.com/docs/reference/glossary/#audience_list) * [Named Users](https://www.airship.com/docs/reference/glossary/#named_user) * [Tags](https://www.airship.com/docs/reference/glossary/#tag) and [Tag Groups](https://www.airship.com/docs/reference/glossary/#tag_group) You can then set Attributes or Tags on channels and Named Users, or group channels into Named Users. See: * [Setting Tags on your audience](https://www.airship.com/docs/guides/audience/tags/#setting-tags-on-your-audience) * [Associating channels with Named Users](https://www.airship.com/docs/guides/audience/named-users/#associate) * [Attributes](https://www.airship.com/docs/guides/audience/attributes/about/) > **Note:** Channel registration is asynchronous, so it may take up to an hour before you can target newly-created channels. ## Segmentation evaluation Airship evaluates segmentation criteria at the Contact level, not individual channels. This means that channel-level data, such as [Device Properties](https://www.airship.com/docs/reference/glossary/#device_properties) and primary device tags, is automatically available to the Contact for segmentation purposes. When [viewing audience counts](https://www.airship.com/docs/guides/audience/segmentation/segments/#generate-audience-count), the results include the total number of Contacts and channels in the audience, as well as the total number of channels and the number of opted-in channels for each [Channel (Engagement)](https://www.airship.com/docs/reference/glossary/#channel_engage) and mobile app platform. Contact-level evaluation enables cross-channel messaging, such as: * Sending an SMS to users who haven't opened the app in 60 days * Sending a follow-up push to users who haven't opened an email * Limiting the frequency of a campaign across all of a user's channels ### Channel-level segmentation Projects in accounts created on or before February 26, 2026, use the channel-level segmentation system, which uses a mix of channel- and Contact-level evaluation. For example, using the criteria: `{custom_tag=gold} AND {ua_language=EN}`: * The channel-level segmentation system targets all channels with a custom tag of `Gold` AND where the device language is set to English. * The Contact-level segmentation system targets all channels of Contacts with a custom tag of `Gold` AND any device where the language is set as English. ### Migration and how to identify your segmentation system All customers will be migrated to the Contact-level evaluation system: * Airship will contact you to coordinate migration. * Until migration is complete, you will not experience any changes to the Airship service or see changes in the dashboard. * After completing migration, mobile apps will require the minimum SDKs Android 19.9 and iOS 19.6. You will not be able to create legacy A/B tests. You can identify your project's current segmentation system. Next to your project name, select the dropdown menu (▼), then **Project Details**. If your project is using the Contact-level system, you will see "Contact-level segmentation: Enabled." If you are on the channel-level system, no segmentation status is listed. # Segments > {{< glossary_definition "segment" >}} Create Segments for a project and also use the same method to define audience conditions in messages and experiments. ## Segment structure You build Segments by adding segmentation data as conditions organized in blocks. For the data you can use in Segments, see [Segmenting your audience](https://www.airship.com/docs/guides/audience/segmentation/segmentation/). Most data types require a value and an operator for evaluating the condition: *True/False*, *Equals*/*Does not equal*, etc. *True/False* determines whether to **include** users for whom the condition is true or false. Most data types use this operator and require no additional selections or values. AND and OR operators between conditions and between blocks determine how they are evaluated. For example, use the AND operator to combine conditions or blocks, and use the OR operator to create alternatives. In the image below, the Segment includes a Text Attribute targeting users whose favorite food is lasagna. The Attribute name is "Favorite Food", the operator is `Equals`, and the value is `lasagna`. ![Creating a Segment in the dashboard](https://www.airship.com/docs/images/segment-builder_hu_4e1acc92b6780a23.webp) *Creating a Segment in the dashboard* The example also shows the use of the Boolean AND. Overall, the Segment dictates including audience members who have the [Tag](https://www.airship.com/docs/reference/glossary/#tag) `airship` and also have the Text Attribute "Favorite Food" that equals `lasagna`. If a user does not meet both conditions, they will not be included in the message audience. ## Create a Segment To create a reusable Segment for your project: 1. Go to **Audience**, then **Segments**, and select **Create Segment**. 1. Enter a name and description, then select **Save and continue**. Search for Segments using this name when targeting message and experiment audiences. 1. Build your Segment as described in the following sections, and then select **Save & exit**. For the API, use the [Segments endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/segments/). > **Note:** The same method of building a Segment is used for the **Target by conditions**, **Target Specific Users**, and **Channel conditions** options for the following: > > * Messages (Message composer) > * Scenes > * In-App Automations > * Feature Flag Configurations > * A/B tests > * Sequence messages > > The same method is also used for setting Sequence trigger conditions. ### Adding conditions When adding conditions, you can search all your segmentation data. The default filter is **All**, and you can select a different filter before or after entering a search term. Search behavior for Tags and Tag Groups varies by filter: | Selected filter | Steps | | --- | --- | | **Tags** | Search for primary device Tags (Tags in the `device` Tag Group) only. | | **Tag Groups** | Select the search field and select a Tag Group, or search for and select a Tag Group, and then search within that Tag Group. | | **All** | This combines the behaviors of the Tags and Tag Groups filters. Use this filter to search for Tags in all Tag Groups. | | **Predictive AI** | Select the search field and then **Predicted to Churn**. You can then select a value: High risk, Medium risk, or Low risk. | | **NPS Category** | Select the search field and then **NPS Category**. You can then select a value: Promoter, Passive, or Detractor. | | **Autogroup** | Select the search field and then **Autogroup**. You can then enter a value, 1-100. Autogroup is only available for accounts not using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation). | In some locations of this interface, you have quick access to your 10 most recently created or modified Segments, [Uploaded lists](https://www.airship.com/docs/reference/glossary/#uploaded_list), and [Subscription lists](https://www.airship.com/docs/reference/glossary/#subscription_list), and all your [Lifecycle lists](https://www.airship.com/docs/reference/glossary/#lifecycle_list). Below the search field, select **Segments**, **Uploaded Lists**, **Subscription Lists**, or **Lifecycle Lists**, and choose from the listed items to add it as a condition. ### Editing conditions and blocks Use these options for adding and editing conditions: * Select the edit icon ( ) to change your selection within a condition, for example, changing a Tag from `airship` to `starship`. * Select the add icon (+) to add a condition to a block. * To duplicate or delete, select the more menu icon (⋮). Deleting all conditions in a block deletes the block. * Select **Add a block +** to add separate conditions. After adding a block, you can hover over it and select **Edit block ** to make changes. ### Setting Boolean logic Select AND or OR between conditions and blocks to apply Boolean logic: * AND = all conditions must be met * OR = any condition must be met When using JSON Attributes, you cannot mix AND and OR selections between conditions or blocks. ### Configuring specific conditions For information about configuring Attribute conditions, see [Targeting your audience using Attributes](https://www.airship.com/docs/guides/audience/attributes/targeting/). For event conditions, see [Event segmentation](https://www.airship.com/docs/guides/audience/events/events/) in the *Events* guide. For device properties, first select an operator. Then, select, search for, or enter a value. Multiple values are evaluated as a Boolean OR. No configuration is required for operators *Empty* and *Not Empty*. ![Configuring device properties in a Segment](https://www.airship.com/docs/images/segment-builder-device-properties_hu_5f68e17a1c0670f9.webp) *Configuring device properties in a Segment* > **Note:** **For device property conditions:** > > * *Equals* and *Does not equal* are the default operators. To make all operators available: > 1. Next to your project name, select the dropdown menu (▼), then **Settings**. > 1. Under **Project settings**, select **Dashboard Settings**. > 1. Enable **Segment Operators**. > > * When using Application Version, SDK Version, or Device OS Version: > * Only semantic versioning is accepted. > * Anything after the third decimal place is excluded. > > For example, `12.2.3-alpha` is evaluated as `12.2.3`. ## Generate audience count When creating a Segment, select **Generate Audience Count** to see the total number of [Contacts](https://www.airship.com/docs/reference/glossary/#contact) for the Segment. **Total Contacts** is the number of Contacts that meet all Segment requirements. Select the show count details icon (eye) to see the following: * The total number of Contacts and channels in the audience * The total number of channels and the number of opted-in channels for each [Channel (Engagement)](https://www.airship.com/docs/reference/glossary/#channel_engage) and mobile app platform If the Segment has three or fewer blocks, you can select **View channel breakdown** to see the same information for a block. Select the regenerate count icon (⟳) after adding or removing criteria. In the [list of all Segments](#manage-segments), select the Segment name to see the Contact and channel counts, if they were already generated when creating the Segment. If not, select **Generate audience count**. Select **Channel breakdown** for the same breakdown available when creating or editing a Segment. Counts appear for seven days, and then you can generate a new count. You can generate the same counts in the Review step in the Message composer. When configuring the Target Specific Users option for an A/B test audience, you can generate the number of channels. > **Note:** For projects using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation), audience counts do not include Contacts: > > * **Total Contacts** is instead **Total Count**, which is the total number of channels in the Segment. > * The count details displays the total number of channels and a breakdown of channels and opted-in channels for each engagement channel and mobile app platform. > * If the Segment has three or fewer blocks, the number of channels in the block displays by default, along with the same channel breakdown. > > Also, in the [list of all Segments](#manage-segments) the channels count is displayed in the **Audience Count** column if it was already generated when creating the Segment. Select **Generate** for any Segment that does not already display its count. Counts appear for seven days, and then you can generate a new count. Select the expand icon ( > ) to see the number of channels and opted-in users per engagement channel and mobile app platform. > **Note:** * Calculations can take multiple minutes to complete, depending on audience size and query complexity. > * For iOS, the opted-in counts only include devices opted-in to notifications and do not include devices where only background push is enabled. > * For Android, the opted-in counts include devices opted-in to notifications as well as devices where only background push is enabled. > * For email, the audience count (within a block and for the Segment) is the sum of Channel IDs for [transactional and commercial](https://www.airship.com/docs/developer/api-integrations/email/commercial-transactional/) messages, and you can hover over the count to see the breakdown. *Opted-in* is for commercial messages only. ## Target a Segment In the API, target a Segment using the `"audience"` object. See: [API: Audience Selection](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/). In the dashboard, you can target a Segment when configuring the Audience step for messages and experiments: 1. (In the Message, Scene, In-App and Automation composers and in A/B tests) Select **Target by conditions**. 1. (In Feature Flag Configurations) Select **Target specific users**, then **Segments**. 1. Define your audience using the same method as when building a Segment. > **Note:** For projects using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation): > > * In the Audience step of the following for messages and A/B tests: > 1. (In the Message composer) Select **Target by specific users**. > 1. (In the Scene and In-App Automation composers and A/B tests) Select **Target specific users**, then **Segments**. > 1. Define your audience using the same method as when building a Segment. > > * When configuring triggers for Scenes and In-App Automations in the Journey map: > 1. Select **Audience conditions**. > 1. Select **Target specific users**, then **Segments**. > 1. Define your audience using the same method as when building a Segment. To enter a Segment into a [Sequence](https://www.airship.com/docs/reference/glossary/#sequence), select the Segment when configuring these triggers in the [Journey Map](https://www.airship.com/docs/reference/glossary/#journey_map): * [Manual Entry](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#manual-entry) * [Date Attribute](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#date-attribute) * [Recurring Schedule](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#recurring-schedule) * [Specific Date and Time](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#specific-date-and-time) When configuring the triggers, you filter the audience members entering the Sequence by setting conditions, which can include a Segment. Setting conditions uses the same method as when building a Segment. See [Trigger](https://www.airship.com/docs/guides/messaging/messages/sequences/create/create/#trigger) in *Create a Sequence*. You can also specify for each message in a Sequence that Contacts in the audience must be a member of a Segment. See the Segmentation option for Conditions in [Add messages to a Sequence](https://www.airship.com/docs/guides/messaging/messages/sequences/create/add-messages/). ## Export a Segment Export a CSV list of audience members in a Segment to add to or reconcile with external systems. You can select [Contact](https://www.airship.com/docs/reference/glossary/#contact) or [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) as the identifier. A list of Channel IDs also includes the channel platform. Once the file is available, Airship sends a download link to your account email address, and you can also download the file from the dashboard. The CSV files are available for download seven days after the request date. While creating or editing a Segment: 1. Select **Export**. 1. Select an identifier. 1. Select **Save and export** to confirm saving the Segment in its current state and starting the export process. The Segment Exports screen will automatically load and display a list of all your requested exports from the last seven days. 1. Once the export status is Done, select the download icon (↓) for the Segment, or follow the link in your email to download the file. One Segment per project can be exported at a time. If you or another user for your project already have an export processing, you must wait until processing is complete before you can request another export. To return to your requested exports, go to **Audience**, then **Segments**, and then **Go to exports**. The processing status and the request date and time are listed for each Segment. To stop processing a Queued or Running export, select the stop icon (■). > **Note:** For projects using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation), you can export a list of Channel IDs and the channel platform for each audience member. There is no option to select Contacts instead. ## Manage Segments Go to **Audience**, then **Segments** to view and manage your saved Segments. All Segments appear in this list, whether created using the API or dashboard, including [Audience Pulse](https://www.airship.com/docs/reference/glossary/#audience_pulse) Segments. Your last modified Segment is listed first. You can search for Segments by name and sort the list by name, date created, or date last modified. Available actions: | Action | Description | Steps | | --- | --- | --- | | **Generate audience count** | Calculate and display the number of Contacts and channels in a Segment. | Select the Segment name, then **Generate audience count**. For more information, see [Generate audience count](#generate-audience-count) above. | | **View details** | Show a Segment's description and targeted audience. | Select a Segment name. | | **Edit**1 | You can edit any part of a Segment. Not available for [Audience Pulse](https://www.airship.com/docs/reference/glossary/#audience_pulse) Segments that update weekly.

**Segmentation data is evaluated at send time.** If you schedule a message that targets a Segment and then edit that Segment, the scheduled message automatically uses the updated Segment criteria. "Scheduled" includes recurring messages. | Select the more menu icon (⋮) for a Segment, then **Edit**, edit as you would a [new Segment](#create-a-segment), then select **Save & exit**. | | **Duplicate**1 | Make a copy of a Segment. Not available for Audience Pulse Segments. | Select the more menu icon (⋮), then **Duplicate**, and then complete the same steps as when [creating a Segment](#create-a-segment). | | **Delete** | Remove a Segment from your project. **Deleting a Segment that is in use may impact messaging.** | Select the more menu icon (⋮), then **Delete**. | {class="table-col-1-20 table-col-2-40"} 1. Some complex Segments created using the API cannot be edited or duplicated in the dashboard. Use the Update Segment API. > **Note:** For projects using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation), use the following reference to manage your Segments: > > | Action | Description | Steps | > | --- | --- | --- | > | **Generate audience count** | Calculate and display the number of [Channel IDs](https://www.airship.com/docs/reference/glossary/#channel_id) in a Segment. | Select **Generate** for a Segment. See [Generate audience count](#generate-audience-count) above. | > | **View details** | Show a Segment's description and targeted audience, as well as the number of Channel IDs and opted-in users per [engagement channel](https://www.airship.com/docs/reference/glossary/#channel_engage) after generating the audience count. | Select the expand icon ( > ) to view details for a Segment and collapse icon ( > ) to close. | > | **Edit**1 | You can edit any part of a Segment. Not available for Audience Pulse Segments that update weekly.

**Segmentation data is evaluated at send time.** If you schedule a message that targets a Segment and then edit that Segment, the scheduled message automatically uses the updated Segment criteria. "Scheduled" includes recurring messages. | Select the edit icon ( > ) for a Segment, edit as you would a [new Segment](#create-a-segment), then select **Save and exit**. | > | **Duplicate**1 | Make a copy of a Segment. Not available for Audience Pulse Segments. | Select the duplicate icon ( > ), enter a name and description, edit as you would a [new Segment](#create-a-segment), then select **Save and exit**. | > | **Delete** | Remove a Segment from your project. **Deleting a Segment that is in use may impact messaging.** | Select the delete icon (trash) for a Segment. | > {class="table-col-1-20 table-col-2-40"} > 1. Some complex Segments created using the API cannot be edited or duplicated in the dashboard. > Use the Update Segment API. # Targeting Specific Users > Set conditions for message and experience audiences. You can target specific users based on user data. A channel must meet your conditions to remain in the audience. ## Set conditions Configure conditions in the Audience step of a message or experiment: * **Feature Flag configurations and A/B test audiences** — Configure conditions after selecting the **Target Specific Users** audience option. * **In-App Automations and Scenes** — Configure conditions under **Channel conditions**. > **Note:** For projects using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation), configure In-App Automation and Scene conditions after selecting the **Target Specific Users** audience option. Configuration steps for each condition are described on this page. Use multiple conditions to build a more complex audience. Multiple conditions in a single message are handled as a boolean AND, meaning a user must meet ALL of the conditions to see a message. Make sure to also specify how messages are handled when audience conditions are not fully met. You can do so at the project level and per message. See [Missed behavior](https://www.airship.com/docs/guides/messaging/project/enable-features/#setting-behavioral-defaults) in *Setting behavioral defaults* and [Override default missed behavior action](https://www.airship.com/docs/guides/messaging/in-app-experiences/configuration/optional-features/#missed-behavior) in *Optional features*. ### App Version Target users based on the version of your app they have installed. For each platform: 1. Select one of: * any version * is equal to * is greater than or equal to * is less than or equal to * is between — *This option includes boundary values. For example, entering versions 4.3 - 5.1 includes 4.3 and 5.1.* 1. Enter the version number or numbers. For Android apps, enter the versionCode. If you don't know this value, you can find it in your Google Play dashboard. > **Tip:** Use the App Version target to contact users on older versions of your app and > encourage them to upgrade to the latest version. ### Device Property Filter the audience eligible to see your message by targeting users who have or do not have a specific [Device Property](https://www.airship.com/docs/reference/glossary/#device_properties). See the [Device Property Tags reference](https://www.airship.com/docs/reference/data-collection/device-properties/#device-property-tags). > **Note:** If a device property is available in a different condition (e.g., Locale), it is not available in the Device Property condition. 1. Select *is* or *is not* from the dropdown menu, then enter a term in the search field and select from the results. A device property tag's type is listed below the tag name. To filter results, select the down arrow icon (▼) below the search box, then select a type of device property. You can select a filter after entering a search term. 1. (Optional) Select the add icon (+) to add another device property. If using an *is not* selector, you cannot add another device property in the same condition. For each additional tag, select *and* or *or* from the dropdown menu. * **and** = all criteria must be met (boolean AND) * **or** = any criteria must be met (boolean OR) ### Locale Target users based on their device's [Locale](https://www.airship.com/docs/reference/glossary/#locale). Select language and country. Country is optional. Select **Add additional locale** for more locales. **Examples:** * To display a message in French to users that have a country code of France, select both French and France. * To display a message in French to all users that have their language set to French, regardless of country setting, select French and do not select a country. ### Location Opt-in Status Target users based on their opt-in status to Location. Select **Opted in** or **Opted out of location**. ### New Users Select **New Users** to ensure your message is seen only by users who have freshly installed your app. New Users are detected on the first app startup, and a user becomes eligible to receive all messages targeting a New User at that time. The actual message has the potential to be displayed in the future, however, depending on the other display rules (e.g., triggers) selected. Users will not see New Users-targeted messages that are published after the first time the app was run. However, they will see edits to message content. > **Note:** Users who remove and reinstall the app become re-eligible for messages targeting New Users. App version updates are not installs. > **Tip:** New Users is useful for targeting users with a "Welcome" message, which the > user will see the first time they open your app. Our SDK will download and > display messages to a new user if they’re set to be triggered on the next > [app open](https://www.airship.com/docs/guides/messaging/in-app-experiences/configuration/triggers/#app-open). > > You can also use the New User target to orchestrate a series of onboarding > messages by triggering a different message to display on the second, third, > and fourth app open, for example. ### Platforms {#platforms} Filter the eligible audience for your message to those on a specific platform. Check the box for *iOS*, *Android*, and/or *Fire OS*. > **Tip:** Create platform-specific content and functionality in your messages. ### Predicted to Churn {#predictive-churn} Target users based on their likelihood to abandon your app. [Predictive Churn](https://www.airship.com/docs/guides/features/intelligence-ai/predictive/predictive-churn/) analyzes your audience for users that exhibit behaviors indicating they are likely to become inactive, and tags the users as High, Medium, or Low Risk. Select a risk group. ### Push Opt-in Status {#opt-in-push} Target users based on their opt-in status to Push. Select **Opted-in** or **Opted-out of push notifications**. > **Tip:** Some example uses include: > > * Present new users who are opted out of push with a message giving them > reasons to opt in during onboarding. > * Retarget long-time users who never opted in to push with messages giving > them reasons to opt in. > * Market features specifically to users who are opted in to push. ### Segments Filter your audience based on whether they meet a set of conditions you define. To configure the condition, follow the same process as building a [Segment](https://www.airship.com/docs/reference/glossary/#segment). > **Note:** For In-App Automations and Scenes, the **Segments** condition is only available for projects using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation). > > If your project uses Contact-level segmentation, add a Segment under **Audience selection** instead: select **Target by conditions**, and then add your Segment. ### Tags {#target-tags} Filter the audience eligible to see your message by targeting users who have or do not have a specific tag or tag group. For [device property tags](https://www.airship.com/docs/reference/glossary/#device_properties) use the [Device Property](#device-property) condition instead. > **Note:** [Server-side](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#client-server) tags cannot be targeted directly. You must first [create a Segment](https://www.airship.com/docs/guides/audience/segmentation/segments/) that includes this data, then select that Segment when configuring your audience. See the [Segments condition](#segments) above. 1. Select **is** or **is not**, and then enter a term in the search field. To filter results, select the down arrow icon (▼) next to the search field, then select **Tags** or a specific tag group. You can select a filter before or after entering a search term. 1. From the search results box, do one of: * Click to **select a tag** from the listed results. A tag's tag group, if any, is listed below the tag name. * **Select a tag group** from the dropdown menu. * Click the button to **create a new tag**. 1. (Optional) Select the add icon (+) to add another tag. If using an *is not* selector, you cannot add another tag in the same condition. For each additional tag, select **and** or **or**. * **and** = all criteria must be met (boolean AND) * **or** = any criteria must be met (boolean OR) > **Tip:** **Example use case:** Educate specific users about your app's Store Finder > feature. > > 1. Create an In-App Message about the Store Finder feature, and target users > who do not have the tag `store_finder`. > > 1. Associate the tag `store_finder` with a message > [action](https://www.airship.com/docs/guides/messaging/in-app-experiences/configuration/button-actions/#set-tag) or when the message is displayed. > This ensures that users who have seen the message will not see it again. # Bulk sending > Send messages to lists of users by providing audience identifiers at send time, either directly in the request or by first creating a bulk audience ID. Bulk sending eliminates the need to add users to your project ahead of time. For example, you can send messages to a list of users generated from [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa) or other reporting platforms without having to re-create your audience criteria. To address existing channels by [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id), use the [Upload and Send](#upload-and-send) method. To send to email addresses, phone numbers, or Open channel addresses, use [Create and Send](#create-and-send), and any unregistered addresses will be registered as new channels at send time. ## Upload and Send Upload and Send targets existing channels by [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) across app, web, email, SMS, and Open channels. To use this method, first prepare a CSV file of Channel IDs (see [CSV formatting](#csv-formatting) for requirements), and then: * **Dashboard:** In the [Message composer](https://www.airship.com/docs/guides/messaging/messages/create/), select **Upload users** in the Audience step, and upload your CSV in the Review step. * **API:** Upload your CSV to the [Create bulk send audience endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to obtain a `bulk_id`, and then send your message using the [Send message with bulk ID](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#bulksendpush) or [Schedule message with bulk ID](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#schedulebulksendpush) endpoint. ## Create and Send *Create and Send* is a way to target recipients of a single channel type by providing a list of user identifiers when creating a message. You can send to email addresses, phone numbers, or Open channel addresses. Unknown identifiers are registered as new channels. You can provide your identifiers as CSV in the dashboard or API, and the API also supports an array method: | Use | ID format | Steps | | --- | --- | --- | | **Dashboard** | CSV | In the [Message composer](https://www.airship.com/docs/guides/messaging/messages/create/), select **Upload users** in the Audience step, and upload your CSV in the Review step. | | **API** | CSV | First, upload identifiers in CSV format to the [Create bulk send audience](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) endpoint to obtain a `bulk_id`. Then, send your message using the [Create and Send a message](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#createandsend) or [Schedule a Create and Send message](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#schedulecreateandsendoperations) endpoint. New channels are created at send time, not when requesting the ID. | | **API** | Array | Include audience identifiers in the `create_and_send` array within the `audience` object when calling the [Create and Send a message](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#createandsend) or [Schedule a Create and Send message](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#schedulecreateandsendoperations) endpoint. | The Create and Send endpoints also support sending to app and web Channel IDs using a `bulk_id`, but it works identically to [Upload and Send](#upload-and-send). ## Usage guidelines Bulk send methods have the following limitations: * Channels must all be of the same type. * Each `bulk_id` can only be used once. After sending, the bulk audience data is deleted. * [CSV columns](#csv-formatting) not prefixed with `ua_` are used for message personalization only and are not saved as channel attributes. * Bulk sends support only a single device type per request. Setting multiple `device_types` returns a 400 response. * [Optimal Send Time](https://www.airship.com/docs/reference/glossary/#optimal_send_time) is not supported. ## CSV formatting CSV files must be smaller than 150 MB, with a maximum of three million rows. The header row is case-sensitive and must contain the required `ua_`-prefixed channel fields as column headers, with values in corresponding fields. Airship ignores rows that are empty or contain malformed channel information. ### Using Channel IDs Use Channel IDs for [Upload and Send](#upload-and-send). * The first column header must be `ua_channel_id`. Entries in the first column contain the target Channel ID. * Your audience must all belong to the same device type. For App channels, this means one of iOS, Android, or Fire OS channels at a time. For example, if you want to send a message to both iOS and Android channels, you must curate separate lists of iOS and Android users and send two separate messages. ### Using email, SMS, or Open channel identifiers Use email addresses, phone numbers, or Open channel identifiers for [Create and Send](#create-and-send). * The first column header varies per channel. Entries in the first column contain the target identifier. * For existing channels, you must provide an `opted_in` date-time value that is newer than an `opted_out` value on the channel. > **Important:** Setting a newer `opted_in` date-time value within the CSV data does not update the `opted_in` value on the channel. It only overrides the `opted_out` value to send the current message. You must update the `opted_in` value using the appropriate channel API to opt it back in to your messaging audience. * Opt-in/out dates must be formatted as ISO 8601 strings. See [Date-Time Format](https://www.airship.com/docs/developer/rest-api/ua/introduction/#date-time-format) in the API reference. Required fields and formatting per channel type: **SMS** * First column header: `ua_msisdn` * First column values: A [MSISDN](https://www.airship.com/docs/reference/glossary/#msisdn) * Additional headers: * `ua_sender` * `ua_opted_in` — The date-time when the user subscribed to messages. **Email** * First column header: `ua_address` * First column values: An email address * Additional headers: * `ua_commercial_opted_in` or `ua_commercial_opted_out` — The date-time when the user subscribed to or unsubscribed from messages. An opt-in or -out date is required for commercial emails. You can also provide dates for `ua_transactional_opted_in` or `ua_transactional_opted_out`, but they are optional. Opt-in/out dates are mutually exclusive. Providing a date for both opted in and opted out in the same row is considered invalid. * `ua_open_tracking_opted_in` or `ua_open_tracking_opted_out` — The date-time when the user opted in to or out of tracking. By default, new channels are opted in to both open and click tracking. A channel can be opted out of tracking by setting an opted out date. The channel can be opted back in to tracking by setting an opted in date that is newer than the opted out date. Providing a date for both opted in and opted out in the same row is considered invalid. * `ua_click_tracking_opted_in` or `ua_click_tracking_opted_out` — Same rules as open tracking above. * `ua_email_suppression_state` — With value `BOUNCE`, `SPAM_COMPLAINT`, `COMMERCIAL_SPAM_COMPLAINT`, or `IMPORTED`. See [Suppression types](https://www.airship.com/docs/developer/api-integrations/email/bounce-handling/#suppression-types) in *Email Bounce Handling and Suppression*. * `timezone` — Format time zones according to the IANA time zone database. For example, `America/Los_Angeles`. **Open** * First column header: `ua_address` * First column values: A unique address that your Open channel uses **CSV example for a Create and Send email** ```text ua_address,ua_commercial_opted_in,name,city,state someone@example.com,2022-04-01T18:45:30,Joe Someone,Portland,OR else@example.com,2022-04-21T16:13:01,Sir Else,Seattle,WA ``` ## Personalization All bulk send methods support [personalization](https://www.airship.com/docs/guides/personalization/about/). Your CSV can contain additional columns for personalizing messages using [Handlebars](https://www.airship.com/docs/reference/glossary/#handlebars). All values in CSV uploads, including numbers, are represented as strings and cannot be used with [math helpers](https://www.airship.com/docs/guides/personalization/handlebars/math-helpers/). When sending to a `bulk_id`, include `"personalization": true` in the `options` object of your send request. Personalization is enabled automatically for the array method and dashboard sends. See [Personalize your Create and Send messages](https://www.airship.com/docs/guides/personalization/sources/create-and-send/). # Audience Pulse > {{< glossary_definition "audience_pulse" >}} Turn user activity data into actionable insights with tier-based reports and AI-powered recommendations. ## About Audience Pulse The Recency, Frequency, Monetary (RFM) model groups users' activities over time into tiers based on: * how recently they performed an event, * how frequently they performed an event, and * the amount of time or money they spent related to an event. Audience Pulse analyzes events across all channels for a user. Events are evaluated for a user on the channel where they occur. Considering activity across all connected channels provides a holistic view of user engagement. Two reports display the tier data: * The [Distribution report](#distribution) visually organizes the relative size of each tier and also displays its user count and audience percentage. * The [Transitions report](#transitions) shows the flow of users between tiers over time. Understanding the distribution can help you gauge user activity. Seeing the transitions between tiers can give you insight on how well you are retaining users or how effective your marketing campaigns are. Initial reports are a "look back" for that period from the current date and from a week prior. For example, if you select a 30-day analysis window, the first reports will cover the past 30 days from today and the past 30 days from seven days ago. Analysis regenerates weekly, providing new and up-to-date data and a wider time span for tracking transitions. To get started, customize tiers with your events, such as purchases, adding to carts, and engaging with editorial content. Once your reports are available, save selected groups as [Segments](https://www.airship.com/docs/reference/glossary/#segment) and target them for more effective campaigns. ### Events to analyze You can set a different event for each tier to tailor the analysis to your specific business goals and user interactions. Select any [Custom Event](https://www.airship.com/docs/reference/glossary/#custom_event) in your project or a Default Event. For Monetary events, you must also select an event property. This is to analyze a value instead of only counting the events. Use Monetary event properties to track metrics like purchase amount, content consumption duration, or any other relevant numerical data. All channels are supported, but Default Events are limited to the following: * App: `app_open` or `message_center_read` * Web: `web_click` or `web_session` * Email: `email_click`, `email_open`, `email_unsubscribe`, or `email_bounce` * SMS: `short_link_click` The tiers are initially configured to analyze app sessions, with each tier using the `app_open` event and the "Time in app" event property for Monetary. See [Events](https://www.airship.com/docs/guides/audience/events/events/) and the [Events Reference](https://www.airship.com/docs/reference/data-collection/events/). ### Analysis window You will select an analysis window matching your user lifecycle. Only users with at least one event occurrence during this period will be analyzed. ### Segments Turn Audience Pulse analysis into actionable information by generating audience [Segments](https://www.airship.com/docs/reference/glossary/#segment) based on selected tiers or transitions. Segments update weekly when analysis regeneration is complete, and segmentation data is evaluated at send time. If you schedule a message that targets an Audience Pulse Segment, the scheduled message automatically uses the latest Segment criteria. "Scheduled" includes recurring messages. You also have the option to save a Segment with its current values only instead of updating weekly. Use cases: * **Personalization** — Different tiers can represent users at different stages of using your app or different levels of interest in your product. Use Segments based on tiers to customize your messaging to each group more appropriately. For example, reward your top tiers and incentivize the lower ones. * **Engagement** — Transitions between tiers are opportunities to provide specific content based on engagement level. Create Segments based on transitions to message users based on which direction they are moving through tiers or which tiers they are moving between. For example, create a re-engagement campaign for users moving down tiers to help retain them, or send a message suggesting users share your app or write a review when they transition into the top tier. ### RFM analysis, tiers, and tagging For each Recency, Frequency, and Monetary category, users are divided into groups: top, middle, and bottom thirds. The groups are in relation to all the other users in the category. Here are a few examples to illustrate: * A user who visited the app the most recently will fall into the top third of the Recency category, because they are in the top 33% of recent visitors. A user who opened the app the furthest back in time in the analysis window will be in the bottom third. * Users who opened the app more times than the bottom two thirds of the audience will fall into the top third of the Frequency category. Users who opened the app fewer times than the top two thirds of the audience will land in the bottom third. * A user who spent the most amount of time in the app will fall into the top third of the Monetary category. A user who spent the least amount of amount of time in the app will land in the bottom third. Each third has a value: 3 for top, 2 for middle, and 1 for bottom. Each user is represented by a combination of the these distributed values. For example: * A user at the top third for Recency, middle for Frequency, and top for Monetary is represented as 323. * A user at the top third for Recency, bottom for Frequency, and middle for Monetary is represented as 312. Users are assigned a tier based on their distribution. Tier descriptions and distributions: | Tier | Description | Distributions | | --- | --- | --- | | **Champions** | Users who performed the analyzed event most recently, most often, and spent the most on it | 333 | | **Loyal Customers** | Users who performed the analyzed event recently, often, and spent a great amount on it | 332, 233 | | **Potential Loyalists** | Recent users who spent a good amount on the event | 223, 323, 322, 232 | | **Recent Customers** | Users who visited most recently but haven't yet transitioned to Potential Loyalist and could easily go down in ranking | 311, 313, 312, 331, 321 | | **Promising** | Users with average Recency scores and potential to increase Frequency or Monetary scores | 222, 221, 212, 213, 231 | | **Need Attention** | Users who haven't performed the analyzed event in a while or have low Frequency and Monetary scores and whose Recency is fading | 123, 113, 211 | | **At Risk** | Users with above average Frequency but who haven't performed the analyzed event for a long time, so are strong candidates to re-engage | 122, 132, 131 | | **Can't Lose Them** | Users who have spent a great amount and performed the analyzed event often but not recently | 133 | | **Hibernating** | Users whose last visit was a while ago, have infrequent visits, and have not spent much | 111, 112, 121 | When assigned a tier, [Tags](https://www.airship.com/docs/reference/glossary/#tag) describing the tier and analysis window date are assigned to users. Tags are added at the [Contact level](https://www.airship.com/docs/guides/audience/your-audience/#data-storage). ## Workflow The following is the general workflow for using Audience Pulse: 1. **Generate tiers** - Analyze activity in your app and assign users to Audience Pulse tiers. Distribution and transition reports are available after analysis completes and tiers are assigned. 1. **Review reports** - Review the Distribution report for the most recent week's analysis and the Transitions report to see how users moved between tiers over time. 1. **Create Segments** - Select tiers or transitions to include in Segments you can use for targeted campaigns. ## Generate tiers Start analysis to assign users to Audience Pulse tiers and create reports: 1. Go to **Audience**, then **Audience Pulse**. 1. Select **Generate tiers**. 1. (Optional) Search for and select an event to analyze for Recency, Frequency, and Monetary. Otherwise, the `app_open` event will be used for each. For Monetary, also select a numeric event property to analyze its values. The menu includes all properties with numeric or `ANY` values. 1. Select a time frame for analysis that approximates your user lifecycle. 1. Select **Start**. The processing time for generating the tiers can vary depending on the size of your audience and the analysis window. You can leave the page during this process. Select **Stop** to cancel the analysis. Once the analysis is complete, the [Distribution](#distribution) and [Transitions](#transitions) reports appear on separate tabs. To view the current analysis window settings, select the gear icon (⚙), and then select **Reset analysis** if you'd like to change it. Your current Audience Pulse analysis will be removed from your project. ## Access reports and create Segments After analysis is complete, Distribution and Transition reports are available in your project. You can create Segments from tiers or transitions but not both. ### Distribution The Distribution report shows the relative size of each tier and also displays its user count and audience percentage. Hover over a tier for more information. ![Audience Pulse Distribution report](https://www.airship.com/docs/images/audience-pulse-distribution_hu_8c245012d55fe0ed.webp) *Audience Pulse Distribution report* To create a Segment from tiers: 1. Select one or more tiers, and they will appear in a list in the sidebar. To remove a tier from the list, select the remove icon (trash) or select it again in the report. Multiple tiers are handled as a boolean OR. Select the sidebar icon (◨) to collapse or expand the sidebar. 1. Select **Create segment from selections**. 1. Enter a Segment name. 1. (Optional) Enter a description. 1. (Optional) Disable **Update weekly** to save the Segment with the current values only. **You cannot change this behavior later.** See [Segments](#segments). 1. Select **Save Segment**. ### Transitions The Transitions report shows the tiers for two selected weeks, as well as the movement of users between tiers from one analysis date to another. By default, high volume transitions are highlighted. These are the top 30% of transitions by number of users who moved between tiers. Uncheck **Show important transitions** to remove highlighting. ![Audience Pulse Transitions report](https://www.airship.com/docs/images/audience-pulse-transitions_hu_ee2b4721c7efbbc2.webp) *Audience Pulse Transitions report* Two columns list the previous and current weeks' tiers. Select new dates to update the displayed transitions. Select a tier in either column, and all transitions in or out will be listed in the sidebar, including the number of users in each transition group. To create a Segment from users who transitioned between tiers for your selected dates: 1. Select tiers to add them to the sidebar list. 1. Select the tier name in the sidebar to include all transition groups or select individual groups. Repeat for additional tiers. Multiple transitions are handled as a boolean OR. Select the sidebar icon (◨) to collapse or expand the sidebar. 1. Select **Create segment from selections**. 1. Enter a Segment name. 1. (Optional) Enter a description. 1. (Optional) Disable **Update weekly** to save the Segment with the current values only. **You cannot change this behavior later.** See [Segments](#segments). 1. Select **Save Segment**. ### AI recommendations [AXP](https://www.airship.com/docs/reference/feature-packages/) [Agentic & Generative AI](https://www.airship.com/docs/guides/features/intelligence-ai/ai/) For [AXP Enterprise plans](https://www.airship.com/docs/reference/feature-packages/), apply AI analysis for deeper insights into audience activities and get actionable recommendations to build more effective, targeted campaigns. To access your recommendations in Audience Pulse, select **✨ AI Insights**. A drawer will expand and display summary cards for five recommendations. Select a card to see the details: * **Why this matters** describes the discovered trend and the importance of addressing it. * **Recommendations** provides the recommended course of action and implementation instructions. Recommendations can include messages, experiences, [Journeys](https://www.airship.com/docs/reference/glossary/#journey), and experiments. If there is an error in processing, you can select **Generate new recommendations**. ![Audience Pulse with AI recommendations](https://www.airship.com/docs/images/audience-pulse-ai_hu_96022f4021ee7d77.webp) *Audience Pulse with AI recommendations* For even more relevant recommendations, add your brand's homepage URL for analysis. Homepage text provides context to ensure insights are a better fit for your brand. The industry setting for your project is also taken into account. To edit your industry and URL, select the dropdown menu (▼) next to your project name, then **Project details**. The current values are processed each time AI recommendations are run. > **Note:** **Opting In to AI Functions** > > If you opted out of AI usage, you must sign an updated contract to enable this feature. Contact your account manager for assistance. > > **Compliance Considerations in Using AI Functions** > > The Service incorporates AI functions, including Generative AI and Agentic AI. > > Generative AI generates content such as Notification copy, images, and Journeys based on your prompts. > > Agentic AI autonomously optimizes, personalizes, or executes cross-channel customer engagement actions, or analyzes audience and performance data, subject to the parameters and controls you set in the Service. These systems operate under human-defined parameters and do not initiate customer-facing actions without human interaction or pre-configured parameters. You are responsible for reviewing Generated Outputs for accuracy, appropriateness, and to ensure they do not violate third-party intellectual property or other rights. Airship does not publish Generated Outputs to end users without approval from the Customer. > > In addition to the applicable terms of your agreement with Airship (e.g., Use of Service, Customer Responsibilities sections), you must comply with the [Airship Acceptable Use Policy](https://www.airship.com/legal/acceptable-use/), which provides additional details about appropriate conduct when using the Service. > > The Service includes safety features to block harmful content, such as content that violates our Acceptable Use Policy. You may not attempt to bypass these protective measures or use content that violates your agreement with Airship. > > About the AI models: > > Airship utilizes Google Gemini and Imagen to generate copy and images for AI Scene screens. The content is created solely with Google's out-of-the-box models, and no customization or fine-tuning with Customer Data is applied. See [Responsible AI](https://cloud.google.com/responsible-ai?hl=en) in Google's *Google Cloud* documentation. ## Manage saved Segments Go to **Audience**, then **Segments** to view and manage your saved Segments. See [Manage Segments](https://www.airship.com/docs/guides/audience/segmentation/segments/#manage-segments). # Ban Lists > {{< glossary_definition "ban_list" >}} {{< badge "axp" >}} > **Important:** You are responsible for maintaining any Ban List, including accuracy and timing of its updates. Please verify with your legal and compliance teams: > > * that any Ban List provided to the Airship Service is compliant with local regulations regarding which End Users should be added to a Ban List; > * scenarios when communications are appropriate to audience members on a Ban List; > * timing of required updates to the Ban List under applicable industry and local regulatory standards. > > Airship does not monitor and is not otherwise responsible for the Ban List content and modifications that have to be made to the Ban List. ## About Ban Lists A Ban List has these components: * **Your record of banned users** — These may be users compiled from "Do not contact me" responses or any other reason to omit them from messaging. You decide the record's format and storage location outside of Airship. Each user must be associated with a [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) or [Named User](https://www.airship.com/docs/reference/glossary/#named_user). We recommend Named User since it maps to all Channel IDs associated with a user. Named User must already be implemented for your project. * **An external [webhook](https://en.wikipedia.org/wiki/Webhook)** — This is an HTTP callback Airship uses to access your record of banned users. You configure the callback and provide Airship with a request URL formatted for querying your data. The webhook must provide a specific response when a match is found. You can format the request URL to use Channel ID, Named User, or both. You can also format it to pass variables. You set a default value for the variable when setting up the URL and can [override the values](#overriding-variable-default-values) for individual messages. * **A Ban List configuration in your Airship project** — You will enter your request URL and confirm Airship is authorized to use it for its intended purpose. Once the above items are in place, this is the Ban List workflow: 1. Airship makes an API call to your webhook for every Channel ID in a message audience. For In-App Automations and Scenes, the Ban List is checked immediately before display. For all other messages, it is checked at send time. 1. Your webhook checks your record of banned users for matches for each Channel ID. If a match is found, the webhook sends a response telling Airship to drop the matched user. 1. Airship drops the send for each match. Only necessary data to prevent users from receiving messages is captured during time of send and is not stored beyond what is necessary for that purpose. Airship does not access or store administrative configurations related to your Ban List. You can set up one Ban List per project. Support for [In-App Automation](https://www.airship.com/docs/reference/glossary/#iaa) and [Scenes](https://www.airship.com/docs/reference/glossary/#scene) requires: [iOS SDK 18.4+](/docs/docs/developer/sdk-integration/apple/ios-changelog/#18.4.0) (Android SDK 18+) > **Warning:** Ban Lists do not work with email addresses or [MSISDNs](https://www.airship.com/docs/reference/glossary/#msisdn) in [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send) CSVs since Ban Lists must match against existing user data. ### Throttling Using an external Ban List can mean a lot of API calls in a short period of time. When configuring your Ban List in Airship, you can set a frequency rate for your requests. The minimum rate is 100 requests per second. ### Bypassing You can bypass your Ban List when sending business-critical or otherwise required messages, such as privacy policy update notifications. Bypass is supported for both the API and dashboard. ### Reporting A `SEND_ABORTED` event occurs when a recipient is dropped from our system before delivery is attempted, with `reason` value `FEED_BANNED_RESPONSE`. `SEND_ABORTED` is not reported for dropped In-App Automations or Scenes. Instead, the app SDK sends an `IN_APP_MESSAGE` event with resolution `IN_APP_MESSAGE_EXCLUSION` when a recipient is dropped. See the events and examples in the *Real-Time Data Streaming API* reference: * [Send Aborted](https://www.airship.com/docs/developer/rest-api/connect/schemas/events/#send-aborted) * [In-App Message Exclusion](https://www.airship.com/docs/developer/rest-api/connect/schemas/events/#in-app-message-exclusion) Each dropped recipient counts toward the Not Sent count in a [message report](https://www.airship.com/docs/guides/reports/message/). ### Webhook requirements When you send a message, Airship will make an API call to your webhook with a URL parameter containing a Named User ID and/or Channel ID. Your server must return a header indicating Airship should drop a matched user from the send. Set up your webhook to return an `X-UA-Segmentation-Action` header to specify an action to be taken by Airship. The only value supported is `drop`, to drop the recipient from the send. This header is valid only for 200- and 400-level status codes and is ignored if provided for 300- or 500-level status codes. It is also ignored if the value is not recognized or the header is missing. Any response with a 200-level status code that does not contain a `drop` value in the header will allow sending to the recipient. ## Formatting your request URL Your request URL is used to retrieve the user data. You will enter it in the dashboard when configuring your Ban List. It comprises your domain, protocol, path, and any variables you want to include. Guidelines: * The URL **must contain** a parameter for the identifiers in your Ban List, one of: * `?channel_id={{$channel.id}}` * `?named_user={{ua_named_user_id}}` * `?named_user={{ua_named_user_id}}&channel_id={{$channel.id}}` * Use double square brackets (`[[var]]`) for send time, or *message-level*, variables. This example request URL has a send time variable `category` and the parameter for Named User: `https://api.example.com/ban-list/[[category]]?named_user={{ua_named_user_id}}`. ## Configuring your Ban List [Owners and Administrators](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels) can configure a project's Ban List. In the Airship dashboard: 1. Next to your project name, select the dropdown menu (▼), then **Settings**. 1. Under **Project settings**, select **Dashboard Settings**. 1. Select **Configure** for Ban List. 1. Configure the list settings: | Setting | Description | Steps | | --- | --- | --- | | **Request URL** | The URL to retrieve the user data from. See [Formatting your request URL](#formatting-your-request-url). | Enter the request URL. | | **Default value for \** | The default value for each send time variable included in the request URL. | Enter a default value. | | **Confirm request URL domain** | The domain in the request URL. For example, `api.example.com`. Do not include the protocol or variables. | Enter the domain. | | **Headers** | Optional. HTTP request headers that may be required to successfully communicate with the external webhook. For example, authorization headers. Header information is not a part of the request URL. | Select **Add header**, and then enter a key and value. Repeat for additional headers. | | **Throttle requests** | Optional. Allows setting a frequency rate for your requests. See [Throttling](#throttling). The minimum rate is 100 requests per second. | Enter the number of API requests to allow per second. | 1. Select **Confirm access rights for request URL**. 1. Select **Done**. Now you can toggle the **Ban List** setting to enable it for your project. ## Overriding variable default values If your project has a Ban List enabled and the request URL includes send time variables, you can override their default values for individual messages. When sending messages using the API, use the [`ban_list_parameters`](https://www.airship.com/docs/developer/rest-api/ua/schemas/push/#pushoptions) push option to override values for variables. In the dashboard, you can override the default values: * In the Delivery step of the Message, A/B Test, Automation composers * In the Delivery step when composing each message in a Sequence In the Delivery step, go to **Ban List**. Each variable is listed under the heading **Default value for \**. Enter a new value for any variable. ## Bypassing your Ban List Using the API, include the [`bypass_ban_list_processing`](https://www.airship.com/docs/developer/rest-api/ua/schemas/push/#pushoptions) push option and set it to `true`. To use this feature in the dashboard, your [project Owner or Administrator](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels) must first enable the option: 1. Next to your project name, select the dropdown menu (▼), then **Settings**. 1. Under **Project settings**, select **Dashboard Settings**. 1. Enable **Bypass Ban List**. > **Important:** Disable this setting when no longer needed to avoid accidentally sending messages to banned users. Then, when creating messages, enable **Bypass Ban List** in the Delivery step. Location per [Composer](https://www.airship.com/docs/reference/glossary/#composer): | Composer | Step | | --- | --- | | [Message](https://www.airship.com/docs/guides/messaging/messages/create/), [A/B Test](https://www.airship.com/docs/guides/experimentation/a-b-tests/messages/), and [Automation](https://www.airship.com/docs/guides/messaging/messages/sequences/create-automation/) | Delivery | | [Sequence](https://www.airship.com/docs/reference/glossary/#sequence) | Delivery for each message in the Sequence | ## Success, Retry, and Error Conditions Airship considers any 2xx response from a feed to be a success and will continue a message using the feed response. Airship considers any 3xx and 5xx codes (except 502/503) to be error conditions. | HTTP status | Result | Behavior | | --- | --- | --- | | 2xx | Success | Airship uses the feed response, even if empty. | | 3xx | Error | Error behavior determined by user. | | 5xx | Error | Error behavior determined by user. | | timeout (60 sec) | Retry | Up to 4 retries, 60 sec between attempts. | | 502/503 | Retry | Up to 4 retries, 60 sec between attempts. | # Retarget a message audience > Send a follow-up push notification or email to an audience segment of a previous message. ## About Audience Retargeting > **Important:** This feature is only available for projects using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation). You can replicate retargeting functionality by creating [Segments](https://www.airship.com/docs/reference/glossary/#segment) based on message engagement events and then targeting those Segments for follow-up messages. *Audience retargeting* is a method for sending follow-up messages to the audience of a parent message. This method is available for push notifications (app and web) and email in the Message composer. When creating your message, you enable the *Generate retargeting segments* setting to make the audience of the current message eligible for follow-up messages. After you send the message, Airship generates the following [Segments](https://www.airship.com/docs/reference/glossary/#segment) for retargeting: * **App and/or Web push notification segments** * *Direct Engagements* — App and web audience members who engaged with the message. * *No Action* — App and web audience members who did not engage with the message. * *All Recipients* — The entire app and web audience.

* **Email segments** * *Email Sent* — The entire email audience. * *Email Opened* — Any email address with at least one open event associated with it for the message. * *Email Clicked* — Any email address with at least one click event associated with it for the message, excluding clicks on the unsubscribe link. Only HTTP and HTTPS links are tracked. * *Email Opened, No Click* — Any email address with at least one open event associated with it for the message, but zero click events. * *Email Sent, not opened or clicked* — Any email address that has no open or click events associated with it for the message. --- You can send a follow-up message to any of your retargeting segments. * The original message is considered the *parent*, and the follow-up message is the *child*. * The selected channels for the follow-up message must be the same as the parent, and the message type for the app channel must be push notification only; app channel message types cannot be combined. * Your follow-up message is a copy of the parent message, with the following differences in the *Audience* step: * *Target Specific Users* is selected and set to your selected retargeting segment. You can add additional criteria to narrow down the retargeted audience. * If the parent message included multiple app platforms, you can disable app platforms, but you cannot select additional ones. > **Note:** **Multi-channel messages** > > If the parent message targets multiple channels, you will be presented with an option to set up follow-up messages for *each channel* individually. Child messages are specific to the channel they are tied to, and never target multiple channels as a parent message can. > > For example, if a parent message targets the email *AND* app channels, the retargeting messages that you create will only be activated on the email *OR* app channel given a qualifiying interaction with the email or push notification, respectively. --- You can generate retargeting segments for up to 5 parent messages per day. There's no limit to the number of follow-up messages you can send from those parents. The [message report](https://www.airship.com/docs/guides/reports/message/) for a parent message shows that retargeting is enabled, along with the complete audience criteria and the audience size (recipient count and percentage of total audience) for each segment. The child message report specifies the segment retargeted from the parent message, and links to its parent message. You can follow the link from the child to the parent to see your original audience criteria. ## Enable Retargeting {#enable} To make the audience of a message eligible for retargeting, enable *Generate retargeting segments* in the *Audience* step of the Message composer. This option is only available when your channels are limited to app platforms, web, and email. ![Enabling retargeting segments](https://www.airship.com/docs/images/generate-retargeting-segments_hu_7f8f93812585e302.webp) *Enabling retargeting segments* > **Tip:** You can keep *Generate retargeting segments* enabled for your child message too. This can help you narrow down a key audience segment in a series of messages. ## View Segment Metrics and Send a Follow-up Message {#follow-up} To take advantage of audience retargeting, you must have already sent a parent message with *Generate retargeting segments* enabled. You can then view the segment metrics and select one as the audience for a follow-up to the parent message, or a subset of that audience. The message type for app platforms is limited to push notification only; you cannot add additional message types. 1. Go to **Messages**, then **Messages Overview**. 1. Select the report icon ( ) for the message containing the audience you want to retarget. 1. Under *Retargeting Segments*, click **Compose follow-up** for the audience you want to target. This opens a copy of the message in the Message composer, with *Target Specific Users* set to your selected audience segment. ![Composing a follow-up from retargeting segments in a message report](https://www.airship.com/docs/images/retargeting-segments_hu_9b562d0bf87d953e.webp) *Composing a follow-up from retargeting segments in a message report* 1. (Optional) Add additional audience criteria to narrow down the audience if necessary. 1. Continue composing your message as normal. > **Note:** When you send or schedule a message to a retargeting segment, Airship does not calculate your audience until send time. Make sure you leave enough time for users to see and interact with the parent message before you send a follow-up message. # SFTP upload for CSV files > You can upload audience lists, attributes, named user association lists, and Coupons data directly to Airship using SFTP. Many CRM platforms export data as CSV files. You can take advantage of Airship's SFTP interface to upload that data to: * **Add users to your project in a reusable** [Audience List](https://www.airship.com/docs/reference/glossary/#audience_list) — The list is labeled "[Uploaded List](https://www.airship.com/docs/reference/glossary/#uploaded_list)" in the dashboard and can be selected as your messaging audience or included in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). * **Set or remove user** [Attributes](https://www.airship.com/docs/reference/glossary/#attributes) —  Attributes can be associated with [Channels](https://www.airship.com/docs/reference/glossary/#channel_dev), [Named Users](https://www.airship.com/docs/reference/glossary/#named_user), [MSISDNs](https://www.airship.com/docs/reference/glossary/#msisdn), or email addresses, but you cannot mix identifiers. For MSISDNs and email addresses, Airship will generate new channels for identifiers we don't recognize. * **Associate** [Channels](https://www.airship.com/docs/reference/glossary/#channel_dev) **with** [Named Users](https://www.airship.com/docs/reference/glossary/#named_user) —  Upon upload, Airship registers channels that are new to your project and creates the named user ID if it does not already exist. * **Add more codes for a [Coupons](https://www.airship.com/docs/reference/glossary/#coupons) campaign** — You can also overwrite existing campaign settings using the values in the CSV file. All uploaded files are encrypted in transit and at rest. You will need: 1. An FTP/SFTP client — Many CRM platforms support SFTP directly, or you can use a client like FileZilla. 1. SSH keys — Airship's implementation of SFTP uses public key authentication. 1. A properly formatted CSV file > **Important:** You must add Custom and Predefined Attributes to your project before setting them on users. Otherwise, setting those Attributes will result in an error. See [Adding Attributes to your project](https://www.airship.com/docs/guides/audience/attributes/adding/). > > JSON Attributes can only be set using the API. > **Tip:** You can also upload audience lists, attributes, named user association lists, and Coupons data in the dashboard. See: > > * [Uploaded Lists](https://www.airship.com/docs/guides/audience/segmentation/audience-lists/uploaded/) > * [Setting Attributes Using a CSV File](https://www.airship.com/docs/guides/audience/attributes/setting/#csv-file) > * [Associating Named Users Using a CSV File](https://www.airship.com/docs/guides/audience/named-users/#csv-file) > * [Coupons: Editing campaigns and adding more codes](https://www.airship.com/docs/guides/personalization/sources/coupons/#editing-campaigns-and-adding-more-codes) ## Format your CSV Prepare your CSV according to the formatting reference for the data you want to upload: * [Attributes CSV format](https://www.airship.com/docs/reference/messages/csv-formatting/#attributes) * [Named user association CSV format](https://www.airship.com/docs/reference/messages/csv-formatting/#named-user-association) * [Uploaded audience list CSV format](https://www.airship.com/docs/guides/audience/segmentation/audience-lists/uploaded/#formatting-your-list) * [Coupons CSV format](https://www.airship.com/docs/guides/personalization/sources/coupons/#formatting-your-csv) ## Generate keys Airship's SFTP implementation uses SSH key pairs for authentication. You will create a pair of keys: a private key for your client and a public key for Airship. The `ssh-keygen` command is included with macOS, Linux, and Windows 10 and later. 1. Open your terminal. On Windows, use PowerShell or Command Prompt. 1. At the command line, enter `ssh-keygen -t rsa`. You can set other options, but the key type must be set to RSA (`-t rsa`). 1. Enter the directory and file name (without extension) for your new keys, e.g., `/Users/your_username/Documents/rsa_keys/`, and optionally enter a passphrase and confirm. This process generates two files based on the file name you provide: * `` contains your private key. * `.pub` contains your public key. 1. Copy the contents of your `.pub` file. This is what you'll paste when adding the key to Airship. --- If you need to remove a key from your project: 1. Next to your project name, select the dropdown menu (▼), then **Settings**. 1. Under **Project settings**, select **SFTP**. 1. Select the delete icon (trash) for a key. ## Add your public key to Airship When you add your public key to Airship, you select the *Purpose* for the key (audience/static lists or attributes), then we generate a username for your SFTP connection. You can use the same key pair to upload both audience/static lists and attributes, but you must add the public key to Airship twice — once for each purpose. In Airship: 1. Next to your project name, select the dropdown menu (▼), then **Settings**. 1. Under **Project settings**, select **SFTP**. 1. Select **Add key** and configure: * **Purpose:** Select **Static Lists** (Uploaded audience lists), **Attributes**, **Attributes Snapshot**, **Named Users**, or **Coupons**. * **Name:** Enter a name to help you identify the key in Airship. * **Public key:** Paste the contents of the `.pub` file you saved in the previous step. 1. Select **Save key**. ## Set up your client and transfer CSVs You can set up any client to use Airship's SFTP interface, using SSH or an SFTP client. Many CRM platforms natively support SFTP. First retrieve configuration information for the [key you added to Airship](#add-your-public-key-to-airship), then enter it in your SFTP client configuration. 1. Next to your project name, select the dropdown menu (▼), then **Settings**. 1. Under **Project settings**, select **SFTP**. 1. Select the view icon (eye) for a key to see values for: * SSH command line * Username * Host: `sftp.airship.com` (`sftp.airship.eu` for EU customers) * Port: `5222` 1. Copy and paste the values from the previous step for use in your SFTP configuration. Authentication also requires [your private key](https://www.airship.com/docs/guides/audience/segmentation/sftp-upload/#generate-keys). ![SFTP client configuration](https://www.airship.com/docs/images/sftp-client-setup_hu_86bc6d506ba22424.webp) *SFTP client configuration* After your connection is set up, you can transfer CSV lists to Airship. --- After file transfer, see the following locations to access each upload type: * **Audience Lists** — Go to **Audience**, then **Lists**, then **Uploaded**. See [Uploaded lists](https://www.airship.com/docs/guides/audience/segmentation/audience-lists/uploaded/). * **Attributes** — Go to **Audience**, then **Attributes**, then **Attribute List**. See [Targeting your audience using attributes](https://www.airship.com/docs/guides/audience/attributes/targeting/) and [Managing attributes](https://www.airship.com/docs/guides/audience/attributes/managing/). * **Coupons** — Next to your project name, select the dropdown menu (▼), then **Settings**. Under **Project settings**, select **Coupons**. See [Coupons](https://www.airship.com/docs/guides/personalization/sources/coupons/). * **Named Users** — To view user data, go to **Audience**, then **Contact Management**. See [Contact Management](https://www.airship.com/docs/guides/audience/contact-management/). * **Attributes** and **Named Users** — For your upload history, go to **Audience**, then **Attributes**, then **Upload History**. 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.

### Audience lists # Lifecycle lists > Use Airship's automatically-generated lifecycle information about your app users to target specific audience members. Audience Lists are messaging recipient groups based on either your own data or automatically-generated app user lifecycle information. You can use audience lists to target specific users. This document explains Lifecycle audience lists. ## About Lifecycle lists *Lifecycle lists* are automatically generated audience lists that capture app open, uninstall, notification, and dormancy information within the past 24 hours, one week, or 30 days. For example, with Lifecycle lists you have a built-in recipient list of all users who have opened your app in the past 7 days. You can disable Lifecycle list auto-generation. There are six Lifecycle list types: * **First App Open** — Opened the app *for the first time* within the given time interval. * **Opened App** — Opened the app within the given time interval. * **Uninstalls** — Devices that have been marked as uninstalled within the given time interval. This list is only available for projects using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation). Note that you must attempt to send a push to an uninstalled device before our system marks it as uninstalled. For details, please see [Detecting Uninstalled Devices](https://www.airship.com/docs/guides/reports/engagement/#detecting-uninstalled-devices). * **Sent Notification** — Devices that have received a notification within the given time interval. * **Direct Opens** — Opened the app directly from a notification within the given time interval. * **Dormant** — Given a time interval **X**, the dormant list contains users that have not opened the app in the last **X** days, but did open the app at least once in the **X** days prior to not opening the app. Tooltips provided in the UI give actual values. > **Note:** Android devices with faulty registrations may be included in the Uninstalls list regardless of whether or not they have an active installation of your app. Consequently, the Uninstalls list may contain a small number of devices that have not actually uninstalled your app. > > See error "Unregistered Device" in Android's [Downstream message error response codes](https://firebase.google.com/docs/cloud-messaging/http-server-ref?hl=en#error-codes). ### List intervals and data The data for each list type is presented in time intervals: * Last Whole Day — *Defined as a period of time commencing and terminating at midnight UTC* * Last 7 Days * Last 14 Days — *Sent Notifications list only* * Last 30 Days In *Audience » Lists » Lifecycle*, each list displays the following per time interval: * Processing status * Days and dates (UTC) * Day and date when the list was last processed * Devices count —  The number of channels associated with the list.

As with [Uploaded Lists](https://www.airship.com/docs/reference/glossary/#uploaded_list), the Devices count includes both users who are opted-in *and* opted-out of push. For example, if you send a push to a list of 1,000 devices where 600 of the devices are opt-in, only 600 devices will receive that push, whereas an in-app message would go to all 1,000 devices. This distinction between a list's Devices count (total devices) and opt-in devices is important to know when viewing a push-to-list's Total Sends metric — Total Sends will correspond to opt-in devices rather than the Devices count. You can also retrieve Lifecycle list information using the [`/lists`](https://www.airship.com/docs/developer/rest-api/ua/operations/static-lists/) API endpoint. ### Use cases You can use Lifecycle lists to target users with personalized messages based on their behaviors: * Specify a Lifecycle list when using the targeting specific users in a message or experiment audience. * Include a Lifecycle list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). * Download Lifecycle lists and add the users to your CRM or other backend system. Use cases per list: * **First App Open:** Target users that have been acquired recently. * Engage with newly-acquired users, sending specific messages that help them understand the benefits of your app. * Guide users to specific areas of your app experience that they might not know about. * Welcome customers and deliver an incentive to open the app again. * **Opened App:** Target users according to active-user status. * If your app is focused on daily or weekly users, e.g., a gaming app, use the *Last Whole Day* or *Last 7 Days* Opened App list to target your most active users. * For lifestyle or retail apps, the *Last 30 Days* list can be used to message users that have engaged, pushing them to a conversion point in the app such as making a purchase. * **Uninstalls:** Target users (via non-push channels) who have uninstalled your app. * Use this list to export devices that have uninstalled your app. Consider messaging them via a different channel regarding the value and utility of mobile notifications. * Augment your data warehouse with this information to investigate why they uninstalled your app. * **Sent Notifications:** Filter out users who have already received a message. * Create a [Segment](https://www.airship.com/docs/reference/glossary/#segment). to filter out users that recently received a message to limit overreach. * Export this list into your email tool to filter our users you have already messaged. * Export this list into your CRM to investigate how users actions outside of the app are influenced by your messaging. * **Dormant:** Target previously active customers who have not engaged with the app recently. * Send special offers to previously active users, incentivizing re-engagement with your app. * Send messages that describe the value and benefit of your app to users who have become dormant. Encourage re-engagement by describing new app versions and features. * Export the dormant list into your CRM and follow up with customers using a different communication method. ## Enabling Lifecycle lists Go to *Audience » Lists » Lifecycle*, and click **Turn On**. The lists are available 24 hours after you enable them; the delay is necessary in order to populate the minimum data required for the shortest time interval, *Last Whole Day*. ## Using Lifecycle Lists * **Message and experiment audiences** — Include a Lifecycle list when using the **Target by conditions** or **Target Specific Users** option in a message, Feature Flag Configuration, or A/B test audience. To send to a Lifecycle list using the API, include `"static_list": "name_of_list"` in the audience object. See [Audience Selection](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/) in the API reference. > **Note:** If a Lifecycle list is processing, you will not be able to send to the list until processing has finished. * **Segments** — Include a Lifecycle list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). * **Add to a backend system** — Download a CSV of your Lifecycle list data for use in another system. Click the arrow icon at the end of a list's row, and save the file. Lifecycle lists can only be downloaded by a [project Owner or Administrator](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels). Each row of the CSV has two columns: device type and channel ID; add the users' channel IDs to your CRM or other backend system. How you use this data depends on your backend integration: 1. **You maintain a mapping of channel IDs to customer IDs (such as named users) in your system.** If this is the case, you have all the information you need! Feed the channel IDs into your backend system for further analysis. 1. **You don't have a mapping, but you do have named users integrated with your app.** In order for the downloaded list data to be usable, you need to get the named user associated with each channel: 1. Use the [named users listing](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#getnameduser) endpoint to get a paginated list of named users and their associated channels. 1. Iterate through the list of named users and their channels, mapping the channels contained in your downloaded list to the appropriate named user. How you accomplish this step is up to you. You may want to write a simple script that compares the named user list generated in step 1 with the downloaded list. 1. Now that each channel on the downloaded list has an associated named user, you may add the channels to your backend system. # Uploaded lists > Create audience lists using your own data. Audience Lists are messaging recipient groups based on either your own data or automatically-generated app user lifecycle information. You can use audience lists to target specific users. This document explains Uploaded audience lists. ## About Uploaded lists Uploaded Lists are reusable audience lists that you create. They are static and updatable. In the API, they are referred to as Static Lists. After you create an Uploaded list, you can: * Select the list when defining your audience for a message. * Include the list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). Because lists are static, they can become outdated very quickly. We encourage active curation of lists, updating them with current data as frequently as possible. ### 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 * Message sent (pushed) to the list The creation date is the initial day one of the 90-day period. Each instance of uploading a new version or sending to the list resets the timestamp to day one. The retention period for an Uploaded list is the same whether uploaded in the Airship dashboard, [using SFTP](https://www.airship.com/docs/guides/audience/segmentation/sftp-upload/), or using the [`/lists`](https://www.airship.com/docs/developer/rest-api/ua/operations/static-lists/) API endpoint. After deletion, the list is removed from the upload history, is no longer visible in the Airship dashboard or through API calls, and is no longer available for audience segmentation. ## Formatting your list Uploaded lists must be in CSV format. CSV files can contain up to 10 million [Named Users](https://www.airship.com/docs/reference/glossary/#named_user) or channel IDs, and be up to 1.5 GB. Each row in the CSV must be an `identifier_type,UUID` pair. The `identifier_type` is one of: `named_user`, `ios_channel`, `android_channel`, `amazon_channel`, `sms_channel`, `email_channel`, `open_channel`, or `web_channel`. The `identifier` is the associated `named_user_id` or `channel_id`. ```text named_user,customer-42 named_user,room-27 ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634 web_channel,d132f5b7-abcf-4920-aeb3-9132ddac3d5a android_channel,52b2b587-0152-4134-a8a0-38ae6933c88a email_channel,ab1a81e3-5af3-4c04-a7ae-d676960e6684 open_channel,6bcf3e63-a38a-44d8-8b0d-2fb5941e74ab sms_channel,ab1a81e3-aaf3-ac04-a7ae-a676960e6684 ``` > **Tip:** Follow the steps in [Export Audience Lists](https://www.airship.com/docs/guides/reports/analytics/tasks-queries/export/#export-audience-list) to download a CSV of device identifiers in [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa). ## Uploading your list You can create up to 100 Uploaded lists per project, either in the dashboard, [using SFTP](https://www.airship.com/docs/guides/audience/segmentation/sftp-upload/), or using the [`/lists`](https://www.airship.com/docs/developer/rest-api/ua/operations/static-lists/) API endpoint. In the dashboard: 1. Go to *Audience » Lists » Uploaded* and click **Create List**. 1. Enter a name. **The name cannot be changed after you save the list.** 1. Enter a description that explains what kind of identifiers are contained within your CSV file. 1. Click **Choose file** and select your file. After selection, you will see the button label change to **Uploaded list**. If you need to choose a different file before saving the list, click *clear* and start again. 1. Click **Save**. You will return to the Uploaded tab, where your new list's status will likely be *Processing*. Once the status is *Ready*, you can send to your new list. Processing time is generally quick but varies depending on the size of your list and server load. Small lists can process within seconds, while large lists may take 5 or 10 minutes. We recommend uploading lists at least a few hours before you need to send to them. This will give you plenty of time to address any potential errors. > **Warning:** When a new list is uploaded, an empty list is created first while the > list identifiers are processed. Please be sure the new list completes > processing and displays a Device count before sending to it. It is > possible to upload a new list and then immediately send to it, resulting > in zero (0) sends because it hasn't completed processing. > **Tip:** You can create an empty list by completing the steps to upload your list but without > uploading a CSV file. This list can be used via both the UI and API, but it > will, of course, send to 0 devices. This may be useful if you want to send a > scheduled message to a list but you haven't yet finished collecting the data > necessary to construct the CSV file. > > Create an empty list, then compose the scheduled message, selecting the > empty list as the audience. Once your CSV file is ready, edit the list and upload the CSV file. The > message will be sent to your intended recipients as long as the upload has > completed processing and the list Status is *Ready* before the scheduled send > time. ### Troubleshooting upload failure {#troubleshooting} Upload may timeout due to a poor internet connection. If so, the file upload must be attempted again. To ensure that the entirety of a given list is successfully processed, we do not support partial uploads. If your Uploaded list shows status *Failed*, review these typical causes: Invalid UUID : One or more of the given UUIDs are invalid. See [this page](https://en.wikipedia.org/wiki/Universally_unique_identifier) for more information on properly formatted UUIDs. Invalid identifier type : You included an identifier type that is not recognized by the uploader. The valid identifier types are `named_user`, `ios_channel`, `android_channel`, `amazon_channel`, `web_channel`, `open_channel`, `sms_channel`, and `email_channel`. Too many identifiers : The list uploader supports up to 10 million `identifier_type,UUID` pairs. Exceeding this limit will result in an error. Too many lists : You can have up to 100 Uploaded lists. Attempting to create more than 100 Uploaded lists will result in an error. Wrong number of columns : CSV files must be two columns, containing `identifier_type,UUID` pairs. Uploading a CSV file with more or fewer than two columns will result in an error. Invalid name/description : Names and descriptions can have lengths of up to 64 and 10,000 characters, respectively. Exceeding either limit will result in an error. ### List data Go to *Audience » Lists » Uploaded*. Each row displays: * List name * Processing status — *Ready* indicates that your list may be used as a message audience, *Processing* indicates that our servers have not yet completed the upload, *Failed* indicates upload failure. * Devices count — The number of [Channel IDs](https://www.airship.com/docs/reference/glossary/#channel_id) associated with the list. This count simply reflects the number of *valid* channel identifiers associated with a given list. Uninstalled channels may still be reflected in the channel count, meaning that sending to a list may result in a send count lower than the channel count. * Users count — The number of named users associated with a given list. May include named user identifiers with no associated channels in Airship. * Created and Last Modified dates When interpreting the Devices count, keep in mind: 1. The Devices count includes both users who are opted-in *and* opted-out of push. For example, if you send a push to a list of 1,000 devices where 600 of the devices are opt-in, only 600 devices will receive that push, whereas an in-app message would go to all 1,000 devices. This distinction between a list's Devices count (total devices) and opt-in devices is important to know when viewing a push-to-list's Total Sends metric — Total Sends will correspond to opt-in devices rather than the Devices count. 1. In order to improve processing time, Airship does not validate that channels are active and addressable when they are processed by our system. We only validate that channels have the right format. This means that any channels that have either been uninstalled or are incorrect but in proper format will still be reflected in the total channel count when the list is done processing, and sending to the list will result in a lower send count than was on the list of channels. > **Warning:** Attribute information may contain a combination of values from both the last *Uploaded list* and the last *successfully processed list*. For example, if the processing step fails after you edit an existing list, the **Status** indicator will read *Failed*, but **Devices** and **Last Modified** will display information from the last *successfully processed list*. ## Using Uploaded Lists Specify an Uploaded list in these locations: * **Segments** — Include an Uploaded list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). * **Message and experiment audiences** — Include an Uploaded list when using the **Target by conditions** or **Target Specific Users** option in a message, Feature Flag Configuration, or A/B test audience. To send to a list using the API, include `"static_list": "name_of_list"` in the audience object. See [Audience Selection](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/) in the API reference. > **Note:** * If an Uploaded list is processing, you will not be able to send to the list until processing has finished. > * If you edited an Uploaded list and it is still processing, you can still send to the list, but the recipients will be from the pre-edited version. ## Managing Uploaded Lists You can edit an Uploaded list's description and CSV file. > **Note:** * You cannot append new values to an existing list by uploading only the new values. To extend a list with additional `identifier_type,UUID` pairs, you must update the original CSV file with those values, then edit the list, uploading the new CSV file that contains both the original pairs and the additions. > > * If you replace a CSV file or upload a CSV for a list that was created without one, be advised that: > * The CSV file will be processed in the same manner as a new list. > * The previously uploaded list is available during processing. > * All existing scheduled messages will use the most recent processed list. "Scheduled" includes recurring messages. 1. Go to *Audience » Lists » Uploaded*. 1. Find the list you want to edit, and select the edit icon ( ). 1. Change the description and/or upload a new CSV file as instructed in [Uploading your list](#uploading-your-list). 1. Click **Save**. --- To delete a list: 1. Go to *Audience » Lists » Uploaded*. 1. Select the delete icon (trash) for a list. After deletion, the list is removed from the upload history, is no longer visible in the Airship dashboard or through API calls, and is no longer available for audience segmentation. # Subscription lists > Create audience lists for specific topics. > **Important:** Please consult your legal counsel before implementing a particular subscription list approach or to help define the subscription purpose in order to address your specific use case or regulatory requirements in your jurisdiction. Audience Lists are messaging recipient groups based on either your own data or automatically-generated app user lifecycle information. You can use audience lists to target specific users. ## About subscription lists A *Subscription list* is an audience list of users who are opted in to messaging about a specific topic. Users can manage their opt-in status per list using a Preference Center. Subscription lists can help with retaining customers, since recipients can opt in and out of content per list rather than opting out of all messaging. After you create a subscription list, you can: * Select the list when defining your audience for a message * Opt a user in to or out of a subscription when the user taps a button in a push notification, in-app message, or web push notification * Trigger an [Automation](https://www.airship.com/docs/reference/glossary/#automation) or [Sequence](https://www.airship.com/docs/reference/glossary/#sequence) when a user opts in to or out of a subscription, or use their opt-in status as a [Condition](https://www.airship.com/docs/reference/glossary/#conditions_event_option) * Include the list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment) * Include the list in a [Preference Center](https://www.airship.com/docs/reference/glossary/#preference_center) * Opt users in to or out of a subscription list when they respond with an [SMS Keyword](https://www.airship.com/docs/reference/glossary/#sms_keyword) --- A subscription list is for either commercial or transactional purposes, which you specify when creating the list and can edit at any time. * **Commercial** — Advertises or promotes a commercial product or service, including content on a website operated for a commercial purpose. * **Transactional** — Facilitates an already agreed-upon transaction, or updates a customer about an ongoing transaction. Verify with your legal team to comply with regulations. When you send to the list, you should only include content related to its purpose. When sending an **email** to a subscription list, you must include an unsubscribe link for opting out of all email messaging, and you can also include an unsubscribe link for that list only. See: [Email unsubscribe links](https://www.airship.com/docs/guides/messaging/messages/content/email/email-unsubscribe-links/). --- You create subscription lists in the dashboard, and you can add users using these methods: * **Automatically** — Enable [Auto opt-in](#auto-opt-in). * **Manually** — [Use the API to add or remove users](#populating-a-list-using-the-api). * **User choice** — Include the list in a [Preference Center](https://www.airship.com/docs/reference/glossary/#preference_center). > **Note:** Airship does not preserve the opt-in/out dates or the source of when or where a user opts into or out of a subscription. Airship does not have access to dates for opt-in/out events unless [Real-Time Data Streaming (RTDS)](https://www.airship.com/docs/reference/glossary/#rtds) is set up. See: [RTDS API: Subscription List Event](https://www.airship.com/docs/developer/rest-api/connect/schemas/events/#subscription-list). ### Auto opt-in [AXP](https://www.airship.com/docs/reference/feature-packages/) When creating a subscription list, you can automatically opt in users to that list by enabling *Auto opt-in*. Both existing and new audience members will be opted in to the list. Auto opt-in cannot be disabled after saving your list. Lists enabled for auto opt-in are not available for use with the *Subscription* trigger for Sequences and Automation. Changing the list type between commercial and transactional does not change the auto opt-in setting. ### Reporting In [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa), you can view a list's eligible subscriber count over time. This count is of unique users subscribed to the list and opted in to notifications at any time during the time frame defined for the report. Go to *Audience » Lists » Subscription* and select the report icon ( ) for a list. The default view is the last 30 days of data. Use the date filter to select a new time frame. Reporting is not available for lists enabled for [Auto opt-in](#auto-opt-in). ## Creating a list You can create up to 20 subscription lists per project. 1. Go to *Audience » Lists » Subscription* and click **Create subscription list**. 1. Enter a name and description for the list. Both appear in your project's [Preference Centers](https://www.airship.com/docs/reference/glossary/#preference_center). Description is optional. * The list ID is automatically generated based on the name and is truncated at 32 characters. * A list ID will not generate for a list name that contains only numbers and/or special characters. * If the name starts with a number and/or special characters, the generated ID omits the leading numbers and/or special characters. * Uppercase letters in the name are converted to lowercase in the ID. * Special characters in the name are converted to underscores in the ID and only appear if followed by numbers or letters. 1. (Optional) Edit the list ID. Letters, numbers, and underscores only, and must start with a letter and end with a letter or number. 32 characters maximum. **You cannot change the list ID later.** 1. Click **Next**. 1. Enable the channels you want to include in the list. 1. Select a subscription type: Commercial or Transactional. Commercial is selected by default. 1. (Optional) Check the *Auto opt-in* checkbox to enable [auto opt-in](#auto-opt-in). **You cannot change this setting after you save the list.** 1. Click **Save**. ## Populating a list using the API Subscription lists are set at the user level to support multi-channel preferences. Use the [Named User Scoped Batch Operations endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#performnameduserscopedbatchoperations) to add or remove users to/from your subscription list. > **Note:** If you are using a single-channel [Preference Center](https://www.airship.com/docs/reference/glossary/#preference_center) created before October 10, 2022, that has not been [migrated to user-level](https://www.airship.com/docs/guides/messaging/features/preference-centers/#migrating-to-a-user-level-preference-center), use the [`/api/channels/subscription_lists` endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#modifychannelsubscriptions) to add or remove individual channels to/from your subscription list. ## Using subscription lists * **Message and experiment audiences** — Include a subscription list when using the **Target by conditions** or **Target Specific Users** option in a message, Feature Flag Configuration, or A/B test audience. To send to a subscription list using the API, use the [`subscription_list` atomic selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/). * **Buttons** [AXP](https://www.airship.com/docs/reference/feature-packages/) — Opt a user in to or out of a subscription list when the user taps a button in your message. See [Add buttons to message content](https://www.airship.com/docs/guides/messaging/messages/buttons/#add-buttons-to-message-content) in *Buttons*. * **Automation and sequence trigger and condition** — Trigger an [Automation](https://www.airship.com/docs/reference/glossary/#automation) or [Sequence](https://www.airship.com/docs/reference/glossary/#sequence) when a user opts in to or out of a subscription, or use their opt-in status as a [Condition](https://www.airship.com/docs/reference/glossary/#conditions_event_option). See: * [Subscription](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#subscription) in *Automation and Sequence Triggers* * [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create-automation/#conditions) in the Setup section of *Create an Automation* * [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create/add-messages/#conditions) in *Add Messages to a Sequence* * **Segments** — Include a subscription list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). For the API, see the [`/api/segments` endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/segments/). * **Preference centers** — Add subscription lists to [Preference Centers](https://www.airship.com/docs/reference/glossary/#preference_center). * **SMS keywords** — Set up [keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/) your audience can use to opt in to or out of your subscription lists. Once added to your project, you can include the keywords in your SMS messages. ## Managing subscription lists Go to *Audience » Lists » Subscription*. The default sort order is by last modified. Each row displays: * List name and ID * Type — *Commercial* or *Transactional*, and *Auto opt-in*, if enabled * Channels * Description * Date and time last modified (browser local time) * Audience count — The number of [Channel IDs](https://www.airship.com/docs/reference/glossary/#channel_id) in the list and the time it was last calculated (browser local time). Select the regenerate icon (arrow-clockwise) to generate an updated count. Lists for all channels appear by default. Click *All channels ▼* and select a channel to filter for only lists enabled for that channel. You can search for lists by name, ID, or description. Select the report icon ( ) to view a list's reporting data. Select the edit icon ( ) to edit a list's name, type, description, or enabled channels. Select the archive icon ( ) to archive. ## Privacy Find documentation for handling individual data privacy rights and complying with data privacy regulations. # Individual Data Privacy Rights Under Data Privacy Laws > How Airship supports individual data privacy rights under applicable data privacy laws, including the EU General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA) In the course of Airship's customers use of the Airship platform (Service), Airship may process Personal Data on behalf of our customers. In that capacity, Airship is the Data Processor and our customer is the Data Controller. The Service provides Customer with a number of controls that Customer may use to retrieve, correct, delete, or restrict personal data, which Customer may use to assist it in connection with its obligations under the applicable data privacy laws including, for example, its obligations relating to responding to requests from data subjects or applicable data protection authorities. To the extent Customer is unable to independently access the relevant personal data within the Service, Airship will provide reasonable cooperation to assist Customer (at Customer's cost to the extent legally permissible) to respond to any requests from data subjects or applicable data protection authorities relating to the processing of personal data via the Service. > **Note:** While this documentation corresponds to the relevant articles under the GDPR, these APIs may be used to respond to similar requests from individuals under other applicable data privacy laws. ## Article 15: Right of access Airship makes available the following APIs to support Customer's extraction of a data subject's personal data from Customer's account on Airship: * [Get Named Users API](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#getnameduser) * [Channel Lookup API](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#getchannel) * [Channel Listing API](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#getchannels) ## Article 16: Right to rectification Airship makes available the following APIs for Customer to use to rectify inaccurate information for a data subject: * If Customer has implemented the "Named User" feature: * [Named User API](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/) * If Customer has not implemented the "Named User" feature: * Rectify data using Airship's SDKs: [Reference for Airship's SDKs](https://www.airship.com/docs/developer/sdk-integration/) * Example: [iOS SDK reference](https://www.airship.com/docs/developer/sdk-integration/apple/installation/getting-started/) * Example: [Android SDK reference](https://www.airship.com/docs/developer/sdk-integration/android/installation/getting-started/) * If Customer is providing personal data about a data subject using Open Channels: * Use the [Open Channels APIs](https://www.airship.com/docs/developer/rest-api/ua/operations/open-channels/) ## Article 17: Right to erasure Airship supports Customers to comply with the data subject's right to erasure in accordance with the following process: * Channel Uninstall API can be used to remove all data associated with a Channel ID from the Airship Service. See the [Channel Uninstall API](https://www.airship.com/docs/developer/rest-api/ua/operations/data-privacy-laws-compliance/#uninstallchannels) for instructions and examples. * Named User Uninstall API removes the Named User and all channel data associated with the Named user from the Airship Service. See the [Named User Uninstall API](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#uninstallnameduser) for instructions and examples. * The Contact Management tool is an alternative to the API methods described above. User data is removed in the same manner as the API methods. See [Deleting a contact](https://www.airship.com/docs/guides/audience/contact-management/#deleting-a-contact) in *Contact Management*. * Customer must provide the specific ID associated with the specific data subject, for example, the hashed ID used as the Named User value, the device token, or the Channel ID. * Customer is responsible for updating their own configuration and use of the Airship Service so that the information regarding the same data subject is no longer provided to Airship. ## Article 18: Right to restrict processing Airship supports opt-in and opt-out or subscribe and unsubscribe controls included as part of the consent process implemented by Customer for its digital assets being used with the Service through [Airship REST APIs](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#modifychannelsubscriptions) as well as through the SDKs using the [Privacy Manager APIs](https://www.airship.com/docs/reference/data-collection/sdk-data-collection/). ## Article 19: Notification obligation regarding rectification or erasure of personal data or restriction of processing If Customer has configured its account on the Service to transmit data to its own servers or to third party applications, Customer has access to that information within the user interface of the Service for purposes of Customer providing notice to data subjects. ## Article 20: Right to data portability Airship makes available the following APIs to support Customer's extraction of a data subject's personal data from Customer's account on Airship: * [Get Named User API](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#getnameduser) * [Channel Lookup API](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#getchannel) * [Channel Listing API](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#getchannels) Once extracted, Customer can provide a copy to the applicable data subject. ## Article 21: Right to object Airship supports opt-in and opt-out or subscribe and unsubscribe controls included as part of the consent process implemented by Customer for its digital assets being used with the Service through [Airship REST APIs](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#modifychannelsubscriptions) as well as through the SDKs using the [Privacy Manager APIs](https://www.airship.com/docs/reference/data-collection/sdk-data-collection/). ## Article 22: Automated individual decision-making, including profiling Customer is responsible for ensuring that its use of the Service does not result in a data subject being subject to a decision based solely on automated processing, including profiling, which produces legal effects concerning him or her or similarly significantly affects him or her.