API сегментации (фильтров)

createFilter

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

Создает новый фильтр.

Тело запроса

Имя	Обязательный	Тип	Описание
auth*	Да	string	Токен доступа к API из Панели управления Pushwoosh.
name*	Да	string	Имя фильтра.
filter_expression*	Да	string	Выражение, составленное в соответствии с правилами языка сегментации. Пример: T(“City”, eq, “Madrid”) для сегментации пользователей, чей город — Мадрид.
application	Нет	string	Код приложения Pushwoosh, который привязывает фильтр к приложению. Опускайте его, если ваш аккаунт не использует высокоскоростную доставку и не требует фильтров, привязанных к приложению. См. примечание под таблицей.
expiration_date	Нет	string	Срок действия фильтра. Фильтр будет автоматически удален в указанную дату, если он не используется в пресете или RSS-ленте.

Что создаёт параметр application

• В вашем аккаунте настроена высокоскоростная доставка: высокоскоростной фильтр.
• Высокоскоростной доставки нет, но ваш аккаунт требует фильтров, привязанных к приложению: обычный фильтр, привязанный к приложению.
• Ни то, ни другое: запрос завершается ошибкой 403 с сообщением the application parameter creates a High-Speed Delivery filter, and High-Speed Delivery is not enabled for this account.

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", // Токен доступа к API из Панели управления Pushwoosh
    "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	Токен доступа к API из Панели управления Pushwoosh.
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	Токен доступа к API из Панели управления Pushwoosh.
name*	string	Имя фильтра.

200

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

Пример

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // Токен доступа к API из Панели управления Pushwoosh
    "name": "filter name"
  }
}

exportSegment

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

Запланированный запрос. Экспортирует список подписчиков, которые подпадают под указанные условия фильтра.

Тело запроса

Имя	Обязательный	Тип	Описание
auth*	Да	string	Токен доступа к API из Панели управления Pushwoosh.
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. Можно получить из API /listFilters или из адресной строки браузера при просмотре фильтра в Панели управления.
applicationCode	Обязательно, если вы используете filterExpression или filterCode.	string	Код приложения Pushwoosh
generateExport	Нет	boolean	По умолчанию установлено значение true, и ответ содержит ссылку для скачивания файла. Если false, в ответе будет отправлено только количество устройств.
format	Нет	string	Устанавливает формат экспортируемого файла: “csv” или “json_each_line”. Если параметр опущен, генерируется CSV-файл.
tagsList	Нет	array	Указывает теги для экспорта. Чтобы получить только определенные теги, массив “exportData” должен содержать значение “tags”.
includeWithoutTokens	Нет	boolean	Установите значение true, чтобы включить пользователей без push-токенов в экспортируемый файл. По умолчанию — false.

200 Successful

{
  "task_id": "177458"
}

Пример

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // обязательно. Токен доступа к API из Панели управления Pushwoosh
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // условия фильтра, синтаксис см. в руководстве по языку сегментации
  "filterCode": "12345-67890",                              // готовый код фильтра, можно использовать вместо filterExpression
  "applicationCode": "00000-AAAAA",                         // Обязательно, если вы используете `filterExpression` или `filterCode`. Код приложения Pushwoosh. Можно получить из API-запроса /listFilters или из адресной строки браузера при просмотре фильтра в Панели управления.
  "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"],                            // необязательно. Указывает теги для экспорта. Чтобы получить только определенные теги, значение "tags" должно быть отправлено в массиве "exportData" или "exportData" должен быть пустым.
  "includeWithoutTokens": true                              // необязательно. Установите значение true, чтобы включить пользователей без push-токенов в экспортируемый файл. По умолчанию — false.
}

Примечание

Справочник по языку сегментации для написания выражений фильтров можно найти здесь.

Например, чтобы экспортировать всех подписчиков определенного приложения, используйте следующие условия фильтра:

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // Токен доступа к API из Панели управления Pushwoosh
  "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

Получает ссылку на CSV-файл с результатами /exportSegment.

Тело запроса

Имя	Тип	Описание
auth*	String	Токен доступа к API из Панели управления Pushwoosh.
task_id*	String	Идентификатор, полученный в ответе на ваш запрос /exportSegment.

200: OK

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

Передайте “task_id”, полученный в ответе на ваш запрос /exportSegment, в теле запроса /exportSegment/result.

В ответе /exportSegment/result вы получите параметр “filename”. Перейдите по ссылке, указанной в значении этого параметра, чтобы автоматически скачать ZIP-архив. Распакуйте архив, чтобы получить CSV- или JSON-файл (в зависимости от “format”, указанного в вашем запросе), содержащий данные устройств.

С 3 апреля 2025 года для скачивания файла потребуется авторизация:

• При скачивании через браузер просто войдите в Панель управления Pushwoosh, чтобы получить доступ.
• При скачивании через серверное ПО включите в ваш запрос следующий заголовок: Authorization: Token YOUR_API_TOKEN

Если вы укажете “exportData” в вашем запросе /exportSegment, скачанный файл будет содержать только запрошенные данные. По умолчанию файл содержит следующие данные пользователя:

Поле	Описание	Пример значения
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	Мобильный рекламный идентификатор (GAID или IDFA), приведенный к нижнему регистру.
Email SHA256	Хеш SHA-256 адреса электронной почты пользователя, приведенного к нижнему регистру и очищенного от пробелов перед хешированием.
Phone SHA256	Хеш SHA-256 номера телефона пользователя в формате E.164 перед хешированием.

Строка для пользователя, у которого нет ни одного из трех идентификаторов, все равно экспортируется, при этом столбцы MADID, Email SHA256 и Phone SHA256 остаются пустыми.

Экспорт активности приложения по пользователям

Примечание

Статистика кампаний возвращает количество открытий/отправлений, сгруппированное по часам и платформам. Столбцов hwid или user_id нет. Чтобы увидеть, какие пользователи и когда открывали приложение, экспортируйте сегмент, построенный на событии PW_ApplicationOpen.

PW_ApplicationOpen работает только для мобильных устройств. Для веб-проекта экспорт сегмента вернет пустые строки, так как это событие там никогда не срабатывает.

1. Создайте выражение фильтра на основе события PW_ApplicationOpen, ограниченное нужным вам периодом. Используйте операторы даты события, например, “открыто вчера”:

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

2. Вызовите /exportSegment с этим filterExpression, applicationCode и exportData: ["hwids", "users"].
3. Вызовите /exportSegment/result с полученным task_id, чтобы скачать CSV-файл со столбцами Hwid и User ID для каждого устройства, открывшего приложение в этом временном окне.

Осторожно

User ID содержит любой идентификатор, который вы назначаете устройству. Если вы его не назначите, будет использоваться HWID. Экспорт показывает, кто открыл приложение в отфильтрованном временном окне. Это не журнал событий по каждому открытию со столбцом временной метки, поэтому создавайте по одному сегменту в день (или на временное окно), если вам нужна детализация по дням.