Segmentation Language

Build precise user segments by using Segmentation Language

Pushwoosh offers a powerful segmentation engine for building granular Segments based on Tag values. Segmentation Language is a specific way of writing and combining segmentation criteria to describe a particular group of users that match those criteria and treat them as a single audience segment.

This article describes the basic concepts and syntax of the Segmentation Language and provides comprehensive examples of building segmentation criteria for various cases.

Basics

Each device in your userbase has specific attributes associated with it via Tag values.

For example, let's say a user named Jane lives in Tokyo, and her age is 28. That user will have the following Tags set for their device:

• Name: Jane

• City: Tokyo

• Age: 28

To target Jane, you will need to describe a segment as follows:

T("Name", eq, "Jane") * T("Age", eq, 28) * T("City", eq, "Tokyo")

This combination of conditions is a filter expression used in Segmentation Language for describing groups of users aka audience Segments.

Filter expressions

Filter expression is a string that contains a condition or a combination of conditions describing the segment you need.

Conditions

Each condition describes a segment of devices that match the criteria specified in that condition.

For example, the following condition builds a segment of users who live in Tokyo:

T("City", e, "Tokyo")

where

• T is a Tag (condition type);

• eq is an operator to apply;

• "Tokyo" is a Tag value users have associated with their devices.

Condition types

There are four condition types you can use for your segmentation:

• A (Application) – describes a segment of devices with a particular app installed;

• T (Tag) – describes a segment of devices with the specified Tag values;

• AT (App-specific tag) – applied in combination with the app codes for tags that are app-specific;

• Event – describes a segment of devices triggered a specific Pushwoosh event;

• Updated – builds a segment of devices based on the last user status update. The updates counted are when the app is first installed on a device, when the device is registered for or unregistered from the app, or some tag on the device changes its value(s).

For filter expression examples, please refer to the Examples section below.

Operations with conditions

For building sophisticated segments, the following operations can be applied to conditions within the filter expression:

Union (+)

Joins the segments, i.e., builds a new segment of users who match at least one of the specified conditions.

For example, to target users who live in Tokyo or in Osaka, you'll need to describe the segment with the following conditions:

T("City", eq, "Tokyo") + T("City", eq, "Osaka")

Analog to logical disjunction (OR).

Intersection (*)

Constructs a segment of users belonging to both segments described by the conditions. Thus, only those users who comply with each condition you specify will be included.

The following expression describes a segment of users who both live in Tokyo and have specified their names:

T("City", eq, "Tokyo") * T("Name", any)

Analog to logical conjunction (AND).

Difference (\)

Builds a segment of users who belong to one of the described segments and do not belong to another.

Users who live in Tokyo but have not given you their names will be described as follows:

T("City", eq, "Tokyo") \ T("Name", any)

Parentheses

Determine the order of operations to perform with the conditions in your filter expression.

For example, the following filter expression will, at first, obtain a segment of the 12345-67890 subscribers whose age is 18 and then subtract all men of that segment:

( A("12345-67890") * T("Age", eq, 18) ) \ T("Gender", eq, "Male")

Tag conditions operators

For each Tag type, their own operators are applied.

Integer Tags Operators

• eq - equal to a specified value

• noteq - not equal to a specified value

• lte - less than or equal to a specified value

• gte - greater than or equal to a specified value

• in - any of specified values

• notin - not equal to any of specified values

• between - in a specified range

• any - devices with any values set for the tag

• notset - devices with no value set for the tag

Integer Tags syntax example: T("int", eq, 42)

String Tags Operators

• eq - equal to a specified value

• noteq - not equal to a specified value

• in - equal to any of specified values

• notin - not equal to any of specified values

• any - devices with any values set for the tag

• notset - devices with no value set for the tag

String Tags syntax example: T("str", eq, "kangaroo")

List Tags Operators

• in - devices with any of the specified tag values

• notin - none of the specified tag values associated with the device

• any - devices with any values set for the tag

• notset - devices with no value set for the tag

List Tags syntax example: T("list", notin, ["kangaroo", "raccoon"])

Date Tags Operators

• eq - equal to the date specified

• noteq - not equal to the date specified

• lte - before of or on the date specified

• gte - after of or on the date specified

• in - equal to any of specified dates

• notin - not equal to any of specified dates

• between - in a specified range

• any - devices with any values set for the tag

• notset - devices with no value set for the tag

• match - matches a specified month of the year and day of the month.

match operator examples:

• AT("XXXXX-XXXXX", "Date tag", match month 4 day 1) - devices that have the "Date tag" set to the 1st of April of any year.

• AT("XXXXX-XXXXX", "Date tag", match month "now" day 13) - devices that have the "Date tag" set to the 13th day of the current month.

• AT("XXXXX-XXXXX", "Date tag", match month "now" day "now+2") - devices that have the "Date tag" set to the day after tomorrow. Common use case: birthday greetings.

• daysago eq - equal to a specified number of days before the present day

• daysago noteq - not equal to a specified number of days before the present day

• daysago lte - less than or equal to a specified number of days before the present day

• daysago gte - greater than or equal to specified number of days before the present day

• daysago between - between the specified numbers of days

daysago operator examples:

• T("Date tag", daysago, eq, 0) - the present day from 00:00 to the current moment;

• T("Date tag", daysago, eq, 1) - from 00:00 of the previous day to 00:00 of the present day;

• T("Date tag", daysago, gte, 1) - all the time to 00:00 of the present day;

• T("Date tag", daysago, lte, 7) - from 00:00 of the day 6 days ago to the current moment;

• T("Date tag", daysago, between, [2,7]) - from 7 to 2 days ago.

date operator examples:

• Updated("11111-11111", lte "2022-12-05 00:00:00")

• T("Date tag", eq "2022-12-05 00:00:00")

Boolean Tags Operators

• eq - equal to a specified value

• noteq - not equal to a specified value

• any - devices with any values set for the tag

• notset - devices with no value set for the tag

Boolean Tags syntax example: T("bool", eq, true)

Price Tags Operators

• eq - equal to a specified value

• noteq - not equal to a specified value

• lte - less than or equal to a specified value

• gte - greater than or equal to a specified value

• in - equal to any of specified values

• notin - not equal to any of specified values

• between - in a specified range

• any - devices with any values set for the tag

• notset - devices with no value set for the tag

Price Tags syntax example: T("price", between, ["4.2", "6.9"])

Version Tags Operators

• eq - equal to a specified value

• noteq - not equal to a specified value

• lte - less than or equal to a specified value

• gte - greater than or equal to a specified value

• in - equal to any of specified values

• notin - not equal to any of specified values

• between - in a specified range

• any - devices with any values set for the tag

• notset - devices with no value set for the tag

Version Tags syntax example: T("version", lte, "4.2")

"Event" conditions operators

Please keep in mind the event conditions are app-specific so the app code should be specified in your filter expressions along with the event name.

Event's count

• count gte - devices triggered the event more than or exactly n times

• count lte - devices triggered the event less than or exactly n times

• count eq - devices triggered the event exactly n times

• count noteq - devices triggered the event any times but not equal to n

Event count syntax example: Event("11111-11111", "Level reached", count gte 10) // 11111-11111 is an app code

Event's date

• date gte - devices triggered the event later than or exactly on the specified date

• date lte - devices triggered the event earlier thar or exactly on the specified date

• date eq - devices triggered the event exactly on the specified date

• date noteq - devices triggered the event whenever but not on the specified date

• date in - devices triggered the event on any of the specified dates

• date notin - devices triggered the event whenever but not on any of the specified dates

• date between - devices triggered the event within a specified period

• daysago eq - event trigger date is equal to a specified number of days before the present day

• daysago noteq - event trigger date is not equal to a specified number of days before the present day

• daysago lte - event trigger date is less than or equal to a specified number of days before the present day

• daysago gte - event trigger date is greater than or equal to specified number of days before the present day

• daysago between - event trigger date is between the specified numbers of days

Event date syntax examples:

• Event("11111-11111", "Level reached", date gte"2022-01-01 01:02:03")

• Event("11111-11111", "Level reached", date in ["2022-01-01 01:02:03", "2022-01-01 02:03:04"]

• Event("11111-11111", "Level reached", date between"2022-01-01 01:02:03" "2022-01-01 02:03:04")

"Updated" conditions operators

Please keep in mind the "Updated" conditions are app-specific so the app code should be specified in your filter expressions along with the event name.

"Updated" filter expression operators

• gte - devices updated their status (app installed, device subscribed/unsubscribed, tags updated) later than or exactly on the specified date

• lte – devices updated their status earlier than or exactly on the specified date

• between – devices updated their status within the specified period

"Updated" syntax examples:

• Updated("11111-11111", between "2022-12-05 00:00:00" "2022-12-06 00:00:00")

• Updated("11111-11111", lte "2022-12-05 00:00:00")

Filter expression examples

Please keep in mind that quotes ("") and backslashes (\) should be escaped with a backslash (\) in JSON queries. For the request example, refer to /exportSegment.

Easy

1. iOS and Android devices with the app installed and with push tokens:

A("11111-11111", ["ios","android"], [with_tokens])

2. iOS and Android devices with the app installed but without push tokens:

A("11111-11111", ["ios","android"], [without_tokens])

3. iOS and Android devices with the app installed, whether they have push tokens or not:

A("11111-11111", ["ios","android"], [with_tokens, without_tokens])

4. All app subscribers who have purchased something in the app:

AT( "11111-11111", "In-App Purchase", gte, 1)

Please take into account that app-specific tags are designated as AT instead of T, and the app code should be specified.

5. The 11111-11111 app subscribers OR 22222-22222 subscribers without tokens:

A("11111-11111") + A("22222-22222", [], [without_tokens])

Hard

1. The filter expression example below includes in a segment all users who:

• are subscribed to the 11111-11111 app on iOS and Android and have push tokens;

• have purchased something in the 22222-22222 app.

A("11111-11111", ["ios", "android"], [with_tokens]) 
* 
AT( "22222-22222", "In-App Purchase", gte, 1)

2. The following example combines users who:

• are subscribed to the 22222-22222 app have no push tokens;

• have purchased Linen Trenchcoat in the 22222-22222 app;

• are subscribed to the 11111-11111 app and have push tokens (if not specified, only devices with tokens are included).

A("11111-11111") 
+ 
(A("22222-22222", [], [without_tokens]) * AT("22222-22222", "In-App Product", in, ["Linen Trenchcoat"]))

Hardcore

1. The example below builds a segment of all users who:

• are subscribed to the 11111-11111 app and have push tokens;

• have purchased something in the 11111-11111 app;

• are subscribed to the 22222-22222 app without push tokens;

• haven't purchased Linen Trenchcoat in the 22222-22222 app.

(A("11111-11111", ["ios"], [with_tokens]) * AT("11111-11111", "In-App Purchase", gte, 1)) 
+ 
(A("22222-22222", [], [without_tokens]) \ AT("22222-22222", "In-App Product", in, ["Linen Trenchcoat"]))