# Segmenting your audience

Build a custom audience of users who share some criteria for message targeting, experiments, and trigger conditions.

<!-- To do:

1. Update links to this page.

-->

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)

<!--

## Building audience groups

When defining an audience for messages or experiments, select **Target by conditions** or **Target Specific Users** (the label depends on your project) to build a custom audience group using audience data.

### Where you build or select an audience

You use the same segment builder and audience data in these places:

| Location | Where |
|----------|--------|
| [Message](https://www.airship.com/docs/guides/messaging/messages/create/) | Audience step |
| [In-App Automation](https://www.airship.com/docs/guides/messaging/in-app-experiences/in-app-automation/create/) | Audience step |
| [Scene](https://www.airship.com/docs/guides/messaging/in-app-experiences/scenes/create/) | Audience step |
| [Feature Flag](https://www.airship.com/docs/guides/experimentation/feature-flags/) | Audience for a Configuration |
| [Message A/B test](https://www.airship.com/docs/guides/experimentation/a-b-tests/messages/) | Audience configuration |

-->

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*

<!--

### channel 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.



### Sequence trigger conditions

You can also filter which audience members enter a [Sequence](https://www.airship.com/docs/reference/glossary/#sequence) using the same audience data and segment builder. In the [Trigger step](https://www.airship.com/docs/guides/messaging/messages/sequences/create/create/#trigger) of *Create a Sequence*, under **Conditions**, build a segment to define who can enter the sequence. You cannot set conditions for the Inactivity or Manual Entry trigger.

-->

### 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}`.

<!--

You can apply channel-level conditions based on:

* Orchestration choices (channel coordination is now a delivery decision, not a targeting option)
* [Subscription list](https://www.airship.com/docs/reference/glossary/#subscription_list) status
* Device group tags
* [Device Properties](https://www.airship.com/docs/reference/glossary/#device_properties)
* Which channel an event occurred on

-->

<!--

## Data types

When defining audiences in messages, experiments, and [Segments](https://www.airship.com/docs/reference/glossary/#segment), you can use the following data types:

* [Attributes](https://www.airship.com/docs/reference/glossary/#attributes)
* [Autogroup](https://www.airship.com/docs/reference/glossary/#autogroup) — For channel-level system, it is segment builder UI. if on contact-level, it isn't. you have to use a channel condition.
* [Lifecycle List](https://www.airship.com/docs/reference/glossary/#lifecycle_list)
* [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id)
* [Channel Coordination](https://www.airship.com/docs/reference/glossary/#channel_coordination) — [update this for current state]
* [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)
* [NPS Category](https://www.airship.com/docs/reference/glossary/#nps_category)
* [NPS Score](https://www.airship.com/docs/reference/glossary/#nps_score)
* [Predicted to Churn status](https://www.airship.com/docs/reference/glossary/#predicted_to_churn)
* [Subscription List](https://www.airship.com/docs/reference/glossary/#subscription_list) — *For accounts created on or after January 28, 2026, the lists must contain [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) or [Named User](https://www.airship.com/docs/reference/glossary/#named_user) as the identifier, not a mix of the two.*
* [Tag](https://www.airship.com/docs/reference/glossary/#tag)

When targeting specific users in In-App Automations and Scenes, you can use these data types:

* App version
* [Device Properties](https://www.airship.com/docs/reference/glossary/#device_properties)
* [Locale](https://www.airship.com/docs/reference/glossary/#locale)
* Location opt-in status
* New users
* Platforms
* [Predicted to Churn status](https://www.airship.com/docs/reference/glossary/#predicted_to_churn)
* Push opt-in status
* Segments
* [Tags](https://www.airship.com/docs/reference/glossary/#tag)
* [Uploaded (Static) List](https://www.airship.com/docs/reference/glossary/#uploaded_list) — *Uploaded Lists are only supported for projects using the [channel-level segmentation system](#channel-level-segmentation). Select them as a channel condition instead.



*Uploaded lists are not supported for accounts created on or after January 28, 2026. Select them as an audience Channel Condition instead.*

*For proejaccounts created on or after January 28, 2026, the lists must contain [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id) or [Named User](https://www.airship.com/docs/reference/glossary/#named_user) as the identifier, not a mix of the two.*

The following are also available for In-App Automations and Scenes when included in a Segment:
* [Attributes](https://www.airship.com/docs/reference/glossary/#attributes)
* [Audience List](https://www.airship.com/docs/reference/glossary/#audience_list)
* [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id)
* [Events](https://www.airship.com/docs/reference/glossary/#events)
* [Named User](https://www.airship.com/docs/reference/glossary/#named_user)
* [Tag](https://www.airship.com/docs/reference/glossary/#tag)

-->

### 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

<!--

| | Value evaluated on Contact | Value evaluated on Channel | Value evaluated on either Contact or Channel |
|--|--|--|--|
| **Value set on Contact** | [Attributes](https://www.airship.com/docs/reference/glossary/#attributes), Custom tags, [Lifecycle List](https://www.airship.com/docs/reference/glossary/#lifecycle_list) | | |
| **Value set on Channel** | | [Autogroup](https://www.airship.com/docs/reference/glossary/#autogroup) | Device tags, [Device Properties](https://www.airship.com/docs/reference/glossary/#device_properties), Default events, [Predictive churn tags](https://www.airship.com/docs/reference/glossary/#predicted_to_churn) |
| **Value set on either Contact or Channel** | | [Subscription List](https://www.airship.com/docs/reference/glossary/#subscription_list) | Predefined events, Custom events, Static lists |

-->

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

<!--

### Setting data on users

For contact-level segmentation (the default for anyone not on channel-level segmentation):

- when creating a new custom tag group or attribute, the values are set to contact level.  
  - Custom tag groups cannot be set at the channel level
  - Attributes cannot be set at the channel level
- Device tags, Device properties, and Default events are set on the channel 
  - The contact level will read the device tags, properties, and default events for segmentation purposes
- Predefined & Custom events, subscription lists, and static lists can be set on the contact or channel level
  - We will no longer support mixed lists (ones with both named user & channel id)
- Lifecycle lists are contact level

### Setting attributes, tags, properties etc

For contact-level segmentation (the default for anyone not on channel-level segmentation):

- when creating a new custom tag group or attribute, the values are set to contact level.  
  - Custom tag groups cannot be set at the channel level
  - Attributes cannot be set at the channel level
- Device tags, Device properties, and Default events are set on the channel 
  - The contact level will read the device tags, properties, and default events for segmentation purposes
- Predefined & Custom events, subscription lists, and static lists can be set on the contact or channel level
  - We will no longer support mixed lists (ones with both named user & channel id)
- Lifecycle lists are contact level

-->

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

<!-- wallet Targeting content to move somewhere else:

Use targeting to address specific members of your messaging [Audience](https://www.airship.com/docs/reference/glossary/#audience).  For mobile wallet passes, you target the passes instead of the pass holders.

* Apply template design changes to passes that have already been distributed.


### Targeting Passes

When you target passes, you select an audience of passes, not pass holders. Passes are targeted via tags only.

Mobile wallet passes are distributed as URLs. After you generate the URLs, you can then distribute the passes via the method of your choosing. If you choose to include the URL with a message via Airship, you will select your audience as described for messaging.

The only other time you need to consider the pass audience is when you want to apply template design changes to Apple Wallet passes that have already been distributed. This is handled by the [Publish feature](#publish).

Add tags to a pass via the API. See:
[Wallet API: Tags](https://www.airship.com/docs/developer/rest-api/wallet/operations/tags/).

### Publishing Passes {#publish}

Use the Publish feature to apply template design changes to a
segment of  Apple Wallet passes that have
already been distributed. When choosing which passes to update, select the radio button for *A specific segment*, then select your previously created
segment. See:
[Publish Tutorial](https://www.airship.com/docs/guides/wallet/user-guide/updating-passes/publish/).

While Publish is not supported for Google Wallet, Google Wallet passes will
automatically update with any changes made to *class* fields. How it works:

* If a class value `class.*` is changed, all passes will be changed.
* On [Update Pass](https://www.airship.com/docs/developer/rest-api/wallet/operations/passes/#updatepass), only that
   pass is updated. Class values are not sent with the update object when
   updating passes, so there is no effect on other passes.

Any field preceded by `class` constitutes a class field. For a full list of
class fields, please visit the
[Google Wallet documentation](https://developers.google.com/pay/save/guides/loyalty/design).

You can also update a segment of passes via the `/segments` endpoint. See:
[Wallet API: Update Segment](https://www.airship.com/docs/developer/rest-api/wallet/operations/segments/#updatesegment).

-->

<!-- wallet Segments content to move somewhere else:

segmentation data: For passes, segments are based on tags only.

tag segments: For passes, you will select tags that you have already created and attached to passes. See: [Wallet API: Tags](https://www.airship.com/docs/developer/rest-api/wallet/operations/tags/).

creating passes:

* [Wallet API: Segments](https://www.airship.com/docs/developer/rest-api/wallet/operations/segments/)
* [Wallet Segments Builder Tutorial](https://www.airship.com/docs/guides/wallet/user-guide/updating-passes/segments-builder/)

For mobile wallet projects, use the Publish feature to updates a segment's passes. When choosing which passes to update, select the radio button for *A specific segment*, then select your previously created segment. See:
[Publish Tutorial](https://www.airship.com/docs/guides/wallet/user-guide/updating-passes/publish/).

* [Wallet Segments Builder: Edit or Delete](https://www.airship.com/docs/guides/wallet/user-guide/updating-passes/segments-builder/#edit-delete)

<!-- wallet content to move somewhere else:

Use targeting to address specific members of your messaging [Audience](https://www.airship.com/docs/reference/glossary/#audience).  For mobile wallet passes, you target the passes instead of the pass holders.

* Apply template design changes to passes that have already been distributed.


### Targeting Passes

When you target passes, you select an audience of passes, not pass holders. Passes are targeted via tags only.

Mobile wallet passes are distributed as URLs. After you generate the URLs, you can then distribute the passes via the method of your choosing. If you choose to include the URL with a message via Airship, you will select your audience as described for messaging.

The only other time you need to consider the pass audience is when you want to apply template design changes to Apple Wallet passes that have already been distributed. This is handled by the [Publish feature](#publish).

Add tags to a pass via the API. See:
[Wallet API: Tags](https://www.airship.com/docs/developer/rest-api/wallet/operations/tags/).

### Publishing Passes {#publish}

Use the Publish feature to apply template design changes to a
segment of  Apple Wallet passes that have
already been distributed. When choosing which passes to update, select the radio button for *A specific segment*, then select your previously created
segment. See:
[Publish Tutorial](https://www.airship.com/docs/guides/wallet/user-guide/updating-passes/publish/).

While Publish is not supported for Google Wallet, Google Wallet passes will
automatically update with any changes made to *class* fields. How it works:

* If a class value `class.*` is changed, all passes will be changed.
* On [Update Pass](https://www.airship.com/docs/developer/rest-api/wallet/operations/passes/#updatepass), only that
   pass is updated. Class values are not sent with the update object when
   updating passes, so there is no effect on other passes.

Any field preceded by `class` constitutes a class field. For a full list of
class fields, please visit the
[Google Wallet documentation](https://developers.google.com/pay/save/guides/loyalty/design).

You can also update a segment of passes via the `/segments` endpoint. See:
[Wallet API: Update Segment](https://www.airship.com/docs/developer/rest-api/wallet/operations/segments/#updatesegment).

-->