细分语言

Pushwoosh 提供了一个强大的细分引擎，用于根据 Tag 值构建精细的细分 (Segments)。细分语言是一种编写和组合细分标准的特定方式，用于描述符合这些标准的特定用户群体，并将其视为单个受众细分。

本文介绍了细分语言的基本概念和语法，并提供了针对各种情况构建细分标准的综合示例。

内联使用，无需保存细分

筛选表达式不必属于已保存的细分 (Segment)。您可以将其直接传递到 NotifySegment 的 expression 字段中，以针对单次发送——这样不会创建细分，并且该表达式也不会存储在账户中。

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "expression": "T(\"City\", eq, \"Tokyo\") * T(\"Age\", gte, 18)",
      "payload": {
        "content": {
          "localized_content": {
            "en": { "ios": { "body": "Hello, Tokyo!" } }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" }
    }
  }'

基础知识

您的用户群中的每个设备都通过 Tag 值关联了特定的属性。

例如，假设一个名为 Jane 的用户住在东京，年龄为 28 岁。该用户的设备将设置以下 Tag：

Name: Jane
City: Tokyo
Age: 28

要定位 Jane，您需要按如下方式描述一个细分：

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

这种条件的组合就是一个筛选表达式，在细分语言中用于描述用户群组，即受众细分 (Segments)。

筛选表达式

筛选表达式是一个字符串，包含一个或多个描述您所需细分的条件组合。

条件

每个条件都描述了符合该条件中指定标准的设备细分。

例如，以下条件构建了一个居住在东京的用户细分：

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

其中

T 是一个 Tag (标签，条件类型)；
eq 是要应用的运算符；
“Tokyo” 是用户设备关联的 Tag 值。

条件类型

以下条件类型可用于细分：

A (Application) – 描述安装了特定应用的设备细分。别名：App, Application；
T (Tag) – 描述具有指定 Tag 值的设备细分；
AT (App-scoped tag) – 在特定应用程序内查找标签值；需要应用程序代码作为第一个参数。别名：Tag；
Event – 描述触发了特定 Pushwoosh 事件的设备细分；
Geo – 描述特定地理半径内的设备细分；
BTTS – 根据最佳发送时间描述设备细分；
Updated – 根据最后更新时间戳描述设备细分；
Segment – 通过其代码引用另一个筛选器/细分；

条件操作

为了构建复杂的细分，可以在筛选表达式中对条件应用以下操作：

并集 (+)

连接各个细分，即构建一个满足至少一个指定条件的用户新细分。

例如，要定位居住在东京或大阪的用户，您需要用以下条件来描述该细分：

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

交集 (*)

构建一个同时属于条件所描述的两个细分的用户细分。因此，只有那些符合您指定的每个条件的用户才会被包含在内。

以下表达式描述了一个既居住在东京又指定了姓名的用户细分：

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

差集 (\)

构建一个属于其中一个细分但不属于另一个细分的用户细分。

居住在东京但未提供姓名的用户将按如下方式描述：

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

括号

确定在筛选表达式中对条件执行操作的顺序。

例如，以下筛选表达式将首先获取 12345-67890 订阅者中年龄为 18 岁的细分，然后减去该细分中的所有男性：

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

Tag 条件运算符

每种 Tag 类型都有其自己的运算符。

列表 Tag 运算符

in - 具有任何指定标签值的设备
notin - 设备未关联任何指定的标签值
any - 为该标签设置了任何值的设备
notset - 未为该标签设置值的设备

日期 Tag 运算符

eq - 等于指定日期
noteq - 不等于指定日期
lte - 在指定日期之前或当天
gte - 在指定日期之后或当天
in - 等于任何指定日期之一
notin - 不等于任何指定日期
between - 在指定范围内
any - 为该标签设置了任何值的设备
notset - 未为该标签设置值的设备
match - 匹配指定的年份中的月份和月份中的日期。

您可以根据重复的日历日期（如生日或周年纪念日）对用户进行细分。在这些情况下，只考虑月份和日期，而年份则被忽略。

AT("XXXXX-XXXXX", "birthday", match month "now" day "now") 定位今天生日的用户（与今天的日期和月份相同）。 使用此功能在用户生日当天发送生日祝福或特别优惠。
AT("XXXXX-XXXXX", "birthday", match month "now" day "now+N") 定位 N 天后生日的用户（月份和日期相同，从今天起 N 天后）。 使用此功能提前为用户做准备，例如发送倒计时消息或即将到来的活动提醒。
AT("XXXXX-XXXXX", "birthday", match month "now" day "now-N") 定位 N 天前生日的用户。 使用此功能发送迟到的生日消息或进行后续跟进，如请求反馈。
AT("XXXXX-XXXXX", "birthday", match month "now" day N) 定位当前月份第 N 天生日的用户，不考虑年份。 当计划与特定日期相关的固定月度活动时使用此功能（例如，每月的 10 号发放忠诚度奖励）。

daysago eq - 等于当前日期之前的指定天数
daysago noteq - 不等于当前日期之前的指定天数
daysago lte - 小于或等于当前日期之前的指定天数
daysago gte - 大于或等于当前日期之前的指定天数
daysago between - 在指定的天数之间

minutesago lte - 小于或等于当前时刻之前的指定分钟数
minutesago gte - 大于或等于当前时刻之前的指定分钟数

daysahead - 从今天 (UTC) 起的 N 到 M 天内，两端均包含

布尔 Tag 运算符

eq - 等于指定值
noteq - 不等于指定值
any - 为该标签设置了任何值的设备
notset - 未为该标签设置值的设备

事件条件运算符

事件计数

count gte - 触发事件次数大于或等于 n 次的设备
count lte - 触发事件次数小于或等于 n 次的设备
count eq - 触发事件次数正好为 n 次的设备
count noteq - 触发事件次数不等于 n 次的设备

事件日期

date gte - 在指定日期之后或当天触发事件的设备
date lte - 在指定日期之前或当天触发事件的设备
date eq - 恰好在指定日期触发事件的设备
date noteq - 在任何时间触发事件但不在指定日期的设备
date in - 在任何指定日期触发事件的设备
date notin - 在任何时间触发事件但不在任何指定日期的设备
date between - 在指定时间段内触发事件的设备
date daysago eq - 事件触发日期等于当前日期之前的指定天数
date daysago noteq - 事件触发日期不等于当前日期之前的指定天数
date daysago lte - 事件触发日期小于或等于当前日期之前的指定天数
date daysago gte - 事件触发日期大于或等于当前日期之前的指定天数
date daysago between - 事件触发日期在指定的天数之间
date daysahead - 事件触发日期在从今天起的指定天数内（区间两端均包含，完整语义请参见上文的日期 Tag 运算符）
date minutesago lte - 事件触发日期小于或等于当前时刻之前的指定分钟数
date minutesago gte - 事件触发日期大于或等于当前时刻之前的指定分钟数

事件平台

根据事件触发的平台筛选事件。

platforms - 平台列表 (例如, [“ios”, “android”])

事件属性

事件条件可以根据事件属性值进行筛选。属性支持各种数据类型及其相应的运算符。

整数事件属性

attribute “name” eq - 属性等于指定值
attribute “name” noteq - 属性不等于指定值
attribute “name” gte - 属性大于或等于指定值
attribute “name” lte - 属性小于或等于指定值
attribute “name” between - 属性在指定范围内
attribute “name” in - 属性等于任何指定值之一
attribute “name” notin - 属性不等于任何指定值
attribute “name” any - 为该属性设置了任何值
attribute “name” notset - 未为该属性设置值

字符串事件属性

attribute “name” eq - 属性等于指定值
attribute “name” noteq - 属性不等于指定值
attribute “name” startswith - 属性以指定前缀开头
attribute “name” endswith - 属性以指定后缀结尾
attribute “name” contains - 属性包含指定子字符串
attribute “name” in - 属性等于任何指定值之一
attribute “name” notin - 属性不等于任何指定值
attribute “name” any - 为该属性设置了任何值
attribute “name” notset - 未为该属性设置值

布尔事件属性

attribute “name” eq - 属性等于 true 或 false
attribute “name” noteq - 属性不等于 true 或 false

日期事件属性

attribute “name” eq - 属性等于指定日期
attribute “name” noteq - 属性不等于指定日期
attribute “name” gte - 属性在指定日期之后或当天
attribute “name” lte - 属性在指定日期之前或当天
attribute “name” between - 属性在指定日期范围内
attribute “name” in - 属性等于任何指定日期之一
attribute “name” notin - 属性不等于任何指定日期
attribute “name” daysago eq/noteq/gte/lte/between - 属性相对于几天前
attribute “name” daysahead from to - 属性在从今天起的指定天数区间内（区间两端均包含，完整语义请参见上文的日期 Tag 运算符）
attribute “name” minutesago gte/lte - 属性相对于几分钟前
attribute “name” any - 为该属性设置了任何值
attribute “name” notset - 未为该属性设置值

价格事件属性

attribute “name” eq - 属性等于指定价格值
attribute “name” noteq - 属性不等于指定价格值
attribute “name” gte - 属性大于或等于指定价格
attribute “name” lte - 属性小于或等于指定价格
attribute “name” between - 属性在指定价格范围内
attribute “name” in - 属性等于任何指定价格之一
attribute “name” notin - 属性不等于任何指定价格
attribute “name” any - 为该属性设置了任何值
attribute “name” notset - 未为该属性设置值

列表事件属性

attribute “name” in - 属性包含任何指定值
attribute “name” notin - 属性不包含任何指定值
attribute “name” any - 为该属性设置了任何值
attribute “name” notset - 未为该属性设置值

其他条件类型

Geo 条件

根据指定半径内的地理位置定位设备。

语法： Geo("<app-code>", <latitude>, <longitude>, <range-in-km>)

BTTS 条件

根据发送通知的最佳时间（一天中的小时，0-23）定位设备。

运算符：

any - 设置了任何最佳发送时间值
eq - 精确小时匹配
noteq - 不等于该小时
gte - 小时大于或等于
lte - 小时小于或等于

Updated 条件

根据设备的最后更新时间戳筛选设备。