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.
To target users based on a unique user ID or other external identifier, do not use Custom Attributes. Instead, target Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual..
Targeting in the dashboard
To target Attributes in the dashboard, create a SegmentA grouping of audience members selected by unique or shared identifiers. Multiple identifiers can be combined within a Segment. and 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
.

The example also shows the use of the boolean AND. Overall, the Segment dictates sending to audience members who have the TagMetadata that you can associate with channels or Named Users for audience segmentation. Generally, they are descriptive terms indicating user preferences or other categorizations, e.g., wine_enthusiast
or weather_alerts_los_angeles
. Tags are case-sensitive. 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.
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.
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 theflight.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 theirsingleFlightDestination
value is missing, because the missing value is treated as"null"
. If one user hassingleFlightDestination
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:
Under Evaluations, choose from the Select a source menu:
Option Description <alias> An alternate name defined for a property. 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. (For string and number properties) Select an operator and enter a value.
(For boolean properties) Select Is true or Is false.
(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.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 format 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. (Optional for arrays in the path) Select First or Last to specify the first or last item in the array. Defaults to Any.
Select the check mark to add the property.
Select Add another for more properties.
(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
Select Done.
For individual messages, you can create a single-use Segment while creating the message. Locations per composer:
You can also create reusable Segments instead of having to recreate your audience selections. See Segments.
Targeting using the API
Use the Attributes audience object 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:
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
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"
}
}
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
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 in the Data Formats section of our API reference.
{
"NOT": {
"attribute": "item_purchased",
"operator": "contains",
"value": "jeans"
}
}
{
"AND": [
{
"attribute": "size",
"operator": "greater",
"value": 12
},
{
"attribute": "size",
"operator": "less",
"value": 15
}
]
}
For JSON Attributes, the Attributes audience object 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 for more information.
{
"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 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 in our API reference.
Operators
Operators per Attribute type:
Attribute type | Operators | API reference |
---|---|---|
Text | equals, contains, less, greater, is_empty | Text Attribute Selector |
Number | equals, contains, less, greater, is_empty | Number Attribute Selector |
Date | equals, before, after, is_empty, range | Date Attribute Selector |
JSON | equals, contains, not_contains, less, greater, is_empty, not_empty1 | JSON Attribute Selector |
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
.
Categories