细分 (筛选器) API

createFilter

POST https://api.pushwoosh.com/json/1.3/createFilter

创建一个新的筛选器。

请求正文

名称	必需	类型	描述
auth*	是	string	来自 Pushwoosh Control Panel 的 API 访问令牌。
name*	是	string	筛选器名称。
filter_expression*	是	string	根据细分语言规则构建的表达式。 示例：T(“City”, eq, “Madrid”) 用于细分城市为马德里的用户。
application	否	string	Pushwoosh 应用程序代码。此参数仅适用于 High-Speed Setup；否则请省略。
expiration_date	否	string	筛选器到期时间。除非在 Preset 或 RSS Feed 中使用，否则筛选器将在指定日期自动删除。

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "name": "filter name"
  }
}

示例

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// 为时区创建筛选器
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // 来自 Pushwoosh Control Panel 的 API 访问令牌
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}

listFilters

POST https://api.pushwoosh.com/json/1.3/listFilters

返回可用细分 (筛选器) 及其条件的列表。

请求正文

名称	必需	类型	描述
auth*	是	string	来自 Pushwoosh Control Panel 的 API 访问令牌。
application*	是	string	Pushwoosh 应用程序代码

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

示例

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}

deleteFilter

POST https://api.pushwoosh.com/json/1.3/deleteFilter

删除一个现有的筛选器。

请求正文

名称	类型	描述
auth*	string	来自 Pushwoosh Control Panel 的 API 访问令牌。
name*	string	筛选器名称。

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

示例

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // 来自 Pushwoosh Control Panel 的 API 访问令牌
    "name": "filter name"
  }
}

exportSegment

POST https://api.pushwoosh.com/api/v2/audience/exportSegment

一个计划请求。导出符合指定筛选器条件的订阅者列表。

请求正文

名称	必需	类型	描述
auth*	是	string	来自 Pushwoosh Control Panel 的 API 访问令牌。
filterExpression*	是	string	筛选器条件
exportData	否	array	要导出的数据。可能的值："hwids"、"push_tokens"、"users"、"tags"、"location"、"ad_identifiers"。包含 "location" 会将 Latitude 和 Longitude 列添加到导出的 CSV 中。如果省略 exportData，则默认导出中会包含 Latitude 和 Longitude。"ad_identifiers" 会添加 MADID、Email SHA256 和 Phone SHA256 列，用于构建 Google Customer Match 或 Meta Custom Audience 源文件 — 请参阅下面的广告标识符导出说明。
filterCode	否	string	预制的 筛选器代码，可用于替代 filterExpression。可以从 /listFilters API 或在 Control Panel 中查看筛选器时从浏览器地址栏获取。
applicationCode	如果使用 filterExpression 或 filterCode，则为必需。	string	Pushwoosh 应用程序代码
generateExport	否	boolean	默认设置为 true，响应中包含下载文件的链接。如果为 false，响应中将只发送设备数量。
format	否	string	设置导出文件的格式：“csv” 或 “json_each_line”。如果省略，则生成 CSV 文件。
tagsList	否	array	指定要导出的 标签。要仅获取特定标签，“exportData” 数组应包含 “tags” 值。
includeWithoutTokens	否	boolean	设置为 true 可在导出的文件中包含没有推送令牌的用户。默认为 false。

200 成功

{
  "task_id": "177458"
}

示例

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // 必需。来自 Pushwoosh Control Panel 的 API 访问令牌
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // 筛选器条件，语法请参考细分语言指南
  "filterCode": "12345-67890",                              // 预制筛选器代码，可替代 filterExpression 使用
  "applicationCode": "00000-AAAAA",                         // 如果使用 filterExpression 或 filterCode，则为必需。Pushwoosh 应用代码。可从 /listFilters API 请求或在 Control Panel 中查看筛选器时从浏览器地址栏获取。
  "generateExport": true,                                   // 如果为 false，响应中将只发送设备数量；默认情况下，响应包含下载 CSV 文件的链接
  "format": "json_each_line",                               // 用于呈现数据的文件格式："csv" – 下载 .csv 文件；"json" – 包含所有导出设备的 JSON 文件；或 "json_each_line" – 每个设备的 JSON 行。如果未指定，默认为 CSV 格式。
  "exportData": ["hwids", "tags"],                          // 可选。要导出的数据。可能的值："hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys", "ad_identifiers"
  "tagsList": ["Name", "Level"],                            // 可选。指定要导出的标签。要仅获取特定标签，应在 "exportData" 数组中发送 "tags" 值，或者 "exportData" 为空。
  "includeWithoutTokens": true                              // 可选。设置为 true 可在导出的文件中包含没有推送令牌的用户。默认为 false。
}

注意

有关编写筛选器表达式的细分语言参考，请参见此处。

例如，要导出特定应用的所有订阅者，请使用以下筛选器条件：

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // 来自 Pushwoosh Control Panel 的 API 访问令牌
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // 引用应用细分的筛选器表达式
  "applicationCode": "AAAAA-BBBBB"           // 必需的 Pushwoosh 应用代码
}

警告

在响应中，您将获得用于获取结果文件的 task_id。然后，在请求正文中调用 /exportSegment/result 并附上该 task_id 以检索结果文件。

exportSegment 结果

POST https://api.pushwoosh.com/api/v2/audience/exportSegment/result

检索包含 /exportSegment 结果的 CSV 链接。

请求正文

名称	类型	描述
auth*	String	来自 Pushwoosh Control Panel 的 API 访问令牌。
task_id*	String	在您的 /exportSegment 响应中收到的标识符。

200: OK

{
  "devicesCount": "24735",
  "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}

将在您的 /exportSegment 响应中收到的 “task_id” 传递到 /exportSegment/result 请求正文中。

在 /exportSegment/result 响应中，您将收到 “filename” 参数。点击该参数值中提供的链接可自动下载一个 ZIP 压缩包。解压该压缩包以检索包含设备数据的 CSV 或 JSON 文件 (取决于您请求中指定的 “format”)。

从 2025 年 4 月 3 日起，下载文件需要授权：

• 如果通过浏览器下载，只需登录 Pushwoosh Control Panel 即可获得访问权限。
• 如果通过服务器软件下载，请在您的请求中包含以下标头： Authorization: Token YOUR_API_TOKEN

如果您在 /exportSegment 请求中指定了 “exportData”，下载的文件将仅包含所请求的数据。默认情况下，文件包含以下用户数据：

字段	描述	示例值
Hwid	设备的硬件 ID	01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8
User ID	将设备与特定用户关联的 User ID。如果未分配 User ID，则使用 HWID。	user8192
Push Token	由云消息网关分配给设备的唯一标识符。了解更多	eeeb2fd7…0fc3547
Type	平台类型 (整数)。	1
Type (humanized)	平台类型 (字符串)。	iOS
Age	默认 Age 标签的值。	29
ApplicationVersion	默认 Application Version 标签的值。	1.12.0.0
City	默认 City 标签的值。	us, boston
TagName	在您账户中创建的标签的值。	TagValue

广告标识符导出

将 "ad_identifiers" 添加到 exportData 中，以获取可直接作为 Google Customer Match 或 Meta Custom Audience 源上传的文件格式。此值为可选加入 — 即使省略 exportData，也绝不会默认包含。它仅在 format 设置为 "csv" 时生效。使用 "json" 或 "json_each_line" 请求它不会返回错误，但以下列会从这些格式中被静默省略。

字段	描述
MADID	移动广告 ID (GAID 或 IDFA)，规范化为小写。
Email SHA256	用户电子邮件的 SHA-256 哈希值，哈希前进行小写和修剪处理。
Phone SHA256	用户电话号码的 SHA-256 哈希值，哈希前采用 E.164 格式。

即使用户没有这三个标识符中的任何一个，其对应行仍会被导出，但 MADID、Email SHA256 和 Phone SHA256 列将为空。

导出每个用户的应用活动

注意

营销活动统计 返回按小时和平台汇总的打开/发送计数。没有 hwid 或 user_id 列。要查看哪些用户在何时打开了应用，请改为导出基于 PW_ApplicationOpen 事件构建的细分。

PW_ApplicationOpen 仅适用于移动端。对于 Web 项目，细分导出不返回任何行，因为该事件永远不会在那里触发。

1. 基于您需要的时间范围，在 PW_ApplicationOpen 事件上构建一个筛选器表达式。使用事件日期运算符，例如“昨天打开”：

Event("AAAAA-BBBBB", "PW_ApplicationOpen", date daysago eq 1)

2. 使用该 filterExpression、applicationCode 和 exportData: ["hwids", "users"] 调用 /exportSegment。
3. 使用返回的 task_id 调用 /exportSegment/result 以下载 CSV 文件，其中包含在该时间窗口内打开应用的每个设备的 Hwid 和 User ID 列。

警告

User ID 持有您分配给设备的任何标识符。如果您不分配，它将回退到 HWID。该导出告诉您在筛选的时间窗口内谁打开了应用。它不是一个带有时间戳列的每次打开事件日志，因此如果您需要按天（或窗口）的粒度，请每天（或每个窗口）构建一个细分。