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. Этот параметр используется только с High-Speed Setup; в противном случае его следует опустить.
expiration_date	Нет	string	Срок действия фильтра. Фильтр будет автоматически удален в указанную дату, если он не используется в Preset или RSS-ленте.

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". Включение "location" добавляет столбцы Latitude и Longitude в экспортируемый CSV. Если exportData опущен, Latitude и Longitude включаются в экспорт по умолчанию.
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 Успешно

{
  "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"
  "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

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

Примечание

Статистика кампаний возвращает количество открытий/отправок, сгруппированное по часам и платформам. В ней нет столбцов 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. Экспорт показывает, кто открыл приложение в отфильтрованном временном окне. Это не журнал событий по каждому открытию со столбцом временной метки, поэтому создавайте по одному сегменту в день (или на временное окно), если вам нужна детализация по дням.