Группы адресов - Сегментирование аудитории¶
Группы позволяют сформировать сегменты аудитории по самым разным критериям персональных данных, занесённых в базу, и по накопленной статистике о поведении подписчика.
Группы-списки - это списки адресов, формируемые вами в явном виде. Участие адреса в такой группе не зависит от его персональных данных и статистики. Выпуск и подсчёт статистик по таким группам несколько быстрее, так как список адресов предопределён.
Группа-фильтр - это динамический список адресов. Участие в такой группе описывается фильтром, применяемым к персональных данным и статистике поведения. Участие адреса в такой группе каждый раз устанавливается в момент проверки в реальном времени. За счёт этого выпуск и подсчёт статистик по таким группам несколько медленнее из-за фильтрации данных.
Фильтр группы-фильтра поддерживает оба формата хранения - и АВО, и КД.
Список групп¶
{
"action" : "group.list"
-- параметры фильтрации, должен быть хотя бы один параметр
--
-- если выбрана последняя порция списка, то ответ содержит "last_page" : 1
--
-- доступны поля
--
-- group.gid -- символический код группы
-- group.name -- название группы
-- group.create.time -- дата и время создания -- Ys, null
-- group.update.time -- дата и время последнего изменения -- Ys, null
-- group.reltype -- число
-- group.relref -- число
-- group.dictnode -- номер узла словаря
-- group.type -- тип группы -- list или filter
-- group.addr_type -- тип адресов -- email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max|any
-- group.expimp -- группа от Экспресс-импорта (!=0) или обычная (==0)
,"filter" : [ фильтр в синтаксисе stat.uni ]
,"order" : [ сортировка ответа в синтаксисе stat.uni ]
,"skip" : количество пропускаемых записей от начала списка, по умолчанию 0
,"first" : количество выбираемых записей после skip, по умолчанию 50, не более 50
}
ответ
{
<общие поля>
,"list" : [
{
"id" : "код группы"
,"name" : "название"
,"type" : "тип группы" -- list или filter
,"addr_type" : "тип адресов" -- email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max
,"create.time" : "дата и время создания" -- Ys, null
,"update.time" : "дата и время последнего изменения" -- Ys, null
,"expimp" : "группа Экспресс-Импорта" -- 0 -пусто-отсутствует - это группа не от Экспресс-импорта
-- -1 -группа от Экспресс-импорта, но данные уже удалены
-- иначе - Экспресс-импорт и данные на месте
,"reltype" : ...
,"relref" : ...
}
...
]
}
Создать группу¶
При создании группы типа filter она первоначально получит пустой набор правил отбора.
До явной установки желаемых правил отбор по такой группе всегда будет давать пусто.
{
"action" : "group.create"
,"id" : "смысловой код группы. символы a-zA-Z0-9_"
-- например "clients2011"
-- параметр необязателен, при отсутствии будет назначен автоматически
,"name" : "название группы" -- параметр обязателен
,"type" : "list | filter" -- параметр обязателен, тип группы
-- list - группа является заранее создаваемым списком
-- filter - группа является набором фильтров для отбора по всей базе
,"addr_type" : "email|msisdn|viber|push|csid|vk|tg|vknotify|pushapp|max" -- параметр обязателен. Тип адресов на работу, с которыми будет ориентирована группа
,"reltype" : ...
,"relref" : ...
}
ответ
Прочитать группу¶
Обратите внимание, что при вызове со списком групп, сообщения об ошибочных кодах групп будут возвращены не в errors (как это было бы при одиночном вызове), а в warnings, так как в целом считается, что вызов закончился успешно.
{
"action" : "group.get"
,"with_filter" : 0 | 1 -- вернуть в ответе, также и фильтр группы
,"id" : "код группы" - для одной группы
-- или
,"id" : [ "код группы", "код группы", ... ] - для списка групп
-- или
,"id" : [ "*" ] - для всех групп
}
ответ
{
<общие поля>
-- для одной группы
,"obj" : {
,"id" : "код группы"
,"name" : "название группы"
,"type" : "тип группы" -- list или filter
,"addr_type" : "тип адресов" -- email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max
,"filter" : [ -- если запрошено
фильтр группы как в вызове group.filter.get
]
,"create.time" : "дата и время создания" -- Ys, null
,"update.time" : "дата и время последнего изменения" -- Ys, null
,"expimp" : "группа Экспресс-Импорта" -- 0 -пусто-отсутствует - это группа не от Экспресс-импорта
-- -1 -группа от Экспресс-импорта, но данные уже удалены
-- иначе - Экспресс-импорт и данные на месте
,"caption" : [
-- если группа от Экспресс-импорта, то тут описана структура данных
-- в том же формате, что используется в вызове импорта
]
,"count" : { -- для группы от Экспресс-импорта
"total" : "количество уникальных адресов"
}
,"reltype" : ...
,"relref" : ...
}
-- или для нескольких групп
,"list" : [
{
содержимое obj для одной группы
}
,{
содержимое obj для другой группы
}
.....
]
,"warnings" : [ -- может отсутствовать
массив аналогичный по структуре массиву errors
содержит ошибки для тех кодов групп из списка, которые ошибочны по тем или иным причинам
]
}
Изменить группу¶
Не указанные параметры не изменяются.
{
"action" : "group.set"
, "id" : "код группы"
,"name" : "название группы" - параметр необязателен
,"reltype" : ...
,"relref" : ...
-- необязательный
,"return_fresh_obj" : "нужно вернуть данные объекта -- да, нет ( 1 | 0 )"
}
ответ
{
<общие поля>
}
если "return_fresh_obj" : "1"
ответ -- как на запрос чтения "action" : "group.get" соответствующей анкеты
Удалить группу¶
ответ
Получить правила фильтрации группы¶
Только для групп с типом filter
{
"action" : "group.filter.get"
,"id" : "код группы"
,"with_in_group" : 0|1 -- включить в ответ информацию об использовании условий in_group/!in_group
-- параметр необязателен, по умолчанию 0
,"expand" : 0|1 -- развернуть фильтр
-- параметр необязателен, по умолчанию 0
-- На месте условия in_group/!in_group подставляется дерево условий включаемой группы-фильтра и добавляются параметры x-op и x-v для понимания того, что было подставлено
-- условия групп-списков не подставляются
-- на месте условия PRF подставляется дерево условий включаемой группы-фильтра и добавляются параметры x-which и x-pid для понимания что было подставлено
-- При каких-либо затруднениях разворачивания фильтра не производится и условие остаётся в оригинальном виде
,"with_check" : 0|1 -- проверь фильтр
-- ошибки будут сообщены через warnings
-- можно, например, узнать не удалена ли группа из in_group
,"with_name" : 0|1 -- для групп, анкет, форм, выпусков добавлять их название в v.name, для выпусков так же добавлять канал выпуска как v.channel
-- 'это замедлит получение результата на больших фильтрах
}
ответ
{
<общие поля>
,"update.time" : "дата-время изменения фильтра" -- Ys
,"obj" : [
массив, описывающий фильтр
]
,"in_group" : {
"count" : 0, -- сколько раз используется in_group или !in_group
"uniq" : 0, -- сколько уникальных групп используется
"list" : [], -- список уникальных групп
"usage : { "group" : 123, ... }, -- какая группа сколько раз использовалась
"depth" : 0, -- максимальный уровень вложенности
"max_reusage" : 0, -- максимально раз использования одной группы
"tree" : "" -- строка представляющая собой дерево вложенности вызовов in_group/!in_group
-- форматирована переводами строк и отступами для обозначения уровня вложенности
},
}
Установить правила фильтрации группы¶
Только для групп с типом filter
ответ
Совпадение одного адреса с фильтром группы¶
Вызов в основном полезен для отладки сложных фильтров - по результату label можно видеть ход выполнения условий, а по safe - результат работы итератеров has.
{
"action" : "group.filter.match"
,"id" : кодгруппы
,"email": "идентификатор подписчика"
,"addr_type" : email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max|id -- тип идентификатора. Параметр необязателен, система сама распознает email или msisdn
}
ответ
{
<общие поля>
"match" : 0 | 1 | null -- с фильтром не совпало, совпало, ошибка фильтра
,"safe" : { ... } -- данные, сохранённые итератерами has в фильтре
,"label" : { ... } -- метки, сохранённые в фильтре при проходе по условиям
}
Снимок группы / Расширить группу-список¶
В указанную группу вносятся адреса из другой группы, условия созданного на ходу фильтра или прочих возможных источников.
Так как источником может быть группа-фильтр или просто фильтр, то вы получаете неизменный "снимок" состояния группы на момент вызова.
Это полезно, например, если требуется провести несколько статистических анализов (не надо для каждого анализа заново искать подписчиков по фильтру и их состав не изменен) или для быстрого выхода рассылки с очень сложным фильтром (можно заранее сделать снимок, скажем ночью, и потом днём очень быстро по нему выпустить рассылку).
Также с помощью этого вызова можно добавлять группу-список участников из других групп, условий фильтра или прочих доступных источников
При асинхронном запуске обработку можно прекратить вызовом track.set
{
"action" : "group.snapshot"
"to" : { -- получатель данных
"id" : "код группы" -- группа-список, в которую будут внесены адреса
-- обратите внимание, что это не вызов импорта списков !
-- если адреса, указанные в источниках email, list, stat.uni на момент
-- вызова отсутствуют в базе, то они не будут созданы и добавлены,
-- для этого есть импорт подписчиков
,"clean" : 0|1 -- полностью очистить группу перед началом внесения
,"resync" : 0|1 -- после внесения новых участников удалить старых, не попадающих более под условия источника
-- имеет смысл с group/group.filter/stat.uni, эквивалентно clean=1 для email/list, но более долго по исполнению
}
,"from" : { -- источник данных одно из
"email" : "адрес подписчика"
,"addr_type" : email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max|id -- тип идентификаторов. Параметр необязателен, система сама распознает email или msisdn
-- или
"list" : [
"адрес подписчика"
,"адрес подписчика"
........
]
,"addr_type" : email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max|id -- тип идентификаторов. Параметр необязателен, система сама распознает email или msisdn
,"sync" : 0|1 -- изменение синхронности запроса, по умолчанию 1 - синхронный
-- или
"group" : код группы
,"sync" : 0|1 -- изменение синхронности запроса, по умолчанию 0 - асинхронный
-- или
"group.filter" : [
фильтр отбора как у group.filter.set
]
,"sync" : 0|1 -- изменение синхронности запроса, по умолчанию 0 - асинхронный
-- или
"stat.uni" : { -- адреса для обработки получаются из запроса Универсальной статистики
-- подразумевается unique = 1
"filter" : [ условие выборки как у запроса в вызове stat.uni ]
,"have" : [ параметр необязателен, условие отбора - поле группировки в фильтре ]
,"cache" : [ настройки кэширования как у запроса в вызове stat.uni ]
,"select" : [ ... ] -- используйте, только если не подходит значение по умолчанию [ "member.email" ]
}
,"addr_type" : email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max|id -- тип идентификаторов. Параметр необязателен, система сама распознает email или msisdn
,"sync" : 0|1 -- изменение синхронности запроса, по умолчанию 0 - асинхронный}
}
,"track.info" : "дополнительная информация, которая будет потом доступна в track.list/get" -- строка 1024 байта. Параметр необязателен
,"sequence.event" : 0|1 -- будет ли добавление в группу генерировать событие для триггеров
-- отсутствие или пусто - событий не будет
}
ответ
{
<общие поля>
-- для асинхронного запроса
,"track.id" : номер -- номер асинхронного запроса для отслеживания с помощью track.*
-- для синхронного запроса -- ничего дополнительного
}
Очистить группу-список¶
Вызов удаляет из участников группы-списка заданные адреса.
Сами адреса в базе остаются ! Удалением адресов из базы занимается вызов member.delete.
{
"action" : "group.clean"
,"id" : "код группы" -- группа-список, из которой будут удалены адреса
-- указание подписчиков одним из способов
,"all" : 1 -- все адреса, быстрый синхронный вызов
-- для получения трекинга или асинхронности, используйте источник "group" c таким же значением что и "id" (более медленно)
или
,"email" : "адрес подписчика" -- вызов синхронный
,"addr_type" : email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max|id -- тип идентификаторов. Параметр необязателен, система сама распознает email или msisdn
или
,"list" : [
"адрес подписчика"
,"адрес подписчика"
........
]
,"addr_type" : email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max|id -- тип идентификаторов. Параметр необязателен, система сама распознает email или msisdn
,"sync" : 0|1 -- изменение синхронности запроса, по умолчанию 1 - синхронный
или
,"group" : код группы участники которой будут удалены
,"sync" : 0|1 -- изменение синхронности запроса, по умолчанию 0 - асинхронный
или
,"group.filter" : [
фильтр отбора как у group.filter.set
]
,"sync" : 0|1 -- изменение синхронности запроса, по умолчанию 0 - асинхронный
или
,"url" : ссылка на файл со списком адресов. по одному на строке. возможно сжатие zip.
,"sync" : 0|1 -- изменение синхронности запроса, по умолчанию 0 - асинхронный
или
,"stat.uni" : { -- адреса для обработки получаются из запроса Универсальной статистики
-- подразумевается unique = 1
"filter" : [ условие выборки как у запроса в вызове stat.uni ]
,"have" : [ параметр необязателен, условие отбора - поле группировки в фильтре ]
,"cache" : [ настройки кэширования как у запроса в вызове stat.uni ]
,"select" : [ ... ] -- используйте, только если не подходит значение по умолчанию [ "member.email" ]
}
,"addr_type" : email|msisdn|viber|csid|push|vk|tg|vknotify|pushapp|max|id -- тип идентификаторов. Параметр необязателен, система сама распознает email или msisdn
,"sync" : 0|1 -- изменение синхронности запроса, по умолчанию 0 - асинхронный
,"track.info" : "дополнительная информация которая будет потом доступна в track.list/get" -- строка 1024 байта. Параметр необязателен
}
ответ