Язык сегментации

Pushwoosh предлагает мощный механизм для создания детализированных сегментов на основе значений тегов. Язык сегментации — это особый способ написания и комбинирования критериев сегментации для описания определенной группы пользователей, которые соответствуют этим критериям, и рассмотрения их как единого сегмента аудитории.

В этой статье описаны основные концепции и синтаксис языка сегментации, а также приведены подробные примеры построения критериев сегментации для различных случаев.

Основы

Каждое устройство в вашей пользовательской базе имеет определенные атрибуты, связанные с ним через значения тегов.

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

• Имя: Джейн
• Город: Токио
• Возраст: 28

Чтобы нацелиться на Джейн, вам нужно будет описать сегмент следующим образом:

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

Эта комбинация условий является фильтрующим выражением, используемым в языке сегментации для описания групп пользователей, то есть сегментов аудитории.

Фильтрующие выражения

Фильтрующее выражение — это строка, которая содержит условие или комбинацию условий, описывающих нужный вам сегмент.

Условия

Каждое условие описывает сегмент устройств, которые соответствуют критериям, указанным в этом условии.

Например, следующее условие создает сегмент пользователей, которые живут в Токио:

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

где

• T — это тег (тип условия);
• eq — это применяемый оператор;
• “Tokyo” — это значение тега, связанное с устройствами пользователей.

Типы условий

Для сегментации доступны следующие типы условий:

• A (Application) — описывает сегмент устройств с установленным определенным приложением. Псевдонимы: App, Application;
• T (Tag) — описывает сегмент устройств с указанными значениями тегов;
• AT (App-specific tag) — применяется в сочетании с кодами приложений для тегов, специфичных для приложения. Псевдоним: Tag;
• Event — описывает сегмент устройств, которые вызвали определенное событие Pushwoosh;
• Geo — описывает сегмент устройств в определенном географическом радиусе;
• BTTS — описывает сегмент устройств на основе их лучшего времени для отправки;
• Updated — описывает сегмент устройств на основе временной метки их последнего обновления;
• Segment — ссылается на другой фильтр/сегмент по его коду;

Операции с условиями

Для создания сложных сегментов к условиям в фильтрующем выражении могут применяться следующие операции:

Объединение (+)

Объединяет сегменты, т.е. создает новый сегмент пользователей, которые соответствуют хотя бы одному из указанных условий.

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

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

Примечание

Эквивалентно логической дизъюнкции (OR). Также может быть записано как оператор or.

Пересечение (*)

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

Следующее выражение описывает сегмент пользователей, которые одновременно живут в Токио и указали свои имена:

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

Примечание

Аналогично логической конъюнкции (AND). Также может быть записано как оператор and.

Разность (\)

Создает сегмент пользователей, которые принадлежат одному из описанных сегментов и не принадлежат другому.

Пользователи, которые живут в Токио, но не указали свои имена, будут описаны следующим образом:

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

Примечание

Эквивалентно логическому отрицанию (NOT). Также может быть записано как оператор not.

Скобки

Определяют порядок выполнения операций с условиями в вашем фильтрующем выражении.

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

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

Операторы условий для тегов

Для каждого типа тегов применяются свои операторы.

Операторы для тегов типа Integer

• eq - равно указанному значению
• noteq - не равно указанному значению
• lte - меньше или равно указанному значению
• gte - больше или равно указанному значению
• in - любое из указанных значений
• notin - не равно ни одному из указанных значений
• between - в указанном диапазоне
• any - устройства с любыми значениями, установленными для тега
• notset - устройства без установленного значения для тега

Пример синтаксиса для тегов типа Integer

T("int", eq, 42)

Операторы для тегов типа String

• eq - равно указанному значению
• noteq - не равно указанному значению
• startswith - начинается с указанного префикса
• endswith - заканчивается указанным суффиксом
• contains - содержит указанную подстроку
• in - равно любому из указанных значений
• notin - не равно ни одному из указанных значений
• any - устройства с любыми значениями, установленными для тега
• notset - устройства без установленного значения для тега

Примеры синтаксиса для тегов типа String

• T("str", eq, "kangaroo") - точное совпадение
• T("str", startswith, "kang") - начинается с “kang”
• T("str", endswith, "roo") - заканчивается на “roo”
• T("str", contains, "nga") - содержит “nga” в любом месте строки

Операторы для тегов типа List

• in - устройства с любым из указанных значений тега
• notin - ни одно из указанных значений тега не связано с устройством
• any - устройства с любыми значениями, установленными для тега
• notset - устройства без установленного значения для тега

Пример синтаксиса для тегов типа List

T("list", notin, ["kangaroo", "raccoon"])

Операторы для тегов типа Date

• eq - равно указанной дате
• noteq - не равно указанной дате
• lte - до или в указанную дату
• gte - после или в указанную дату
• in - равно любой из указанных дат
• notin - не равно ни одной из указанных дат
• between - в указанном диапазоне
• any - устройства с любыми значениями, установленными для тега
• notset - устройства без установленного значения для тега
• match - соответствует указанному месяцу года и дню месяца.

Примеры оператора match

• AT("XXXXX-XXXXX", "Date tag", match month 4 day 1) - устройства, у которых “Date tag” установлен на 1 апреля любого года.
• AT("XXXXX-XXXXX", "Date tag", match month "now" day 13) - устройства, у которых “Date tag” установлен на 13-й день текущего месяца.
• AT("XXXXX-XXXXX", "Date tag", match month "now" day "now+2") - устройства, у которых “Date tag” установлен на послезавтра. Частый случай использования: поздравления с днем рождения.

Примеры оператора 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 - между указанным количеством дней

Примеры оператора daysago

• T("Date tag", daysago, eq, 0) - текущий день с 00:00 до текущего момента
• T("Date tag", daysago, eq, 1) - с 00:00 предыдущего дня до 00:00 текущего дня
• T("Date tag", daysago, gte, 1) - все время до 00:00 текущего дня
• T("Date tag", daysago, lte, 7) - с 00:00 дня 6 дней назад до текущего момента
• T("Date tag", daysago, between, [2,7]) - от 7 до 2 дней назад.

• minutesago lte - меньше или равно указанному количеству минут до текущего момента
• minutesago gte - больше или равно указанному количеству минут до текущего момента

Примеры оператора minutesago

• T("Date tag", minutesago, lte, 30) - последние 30 минут;
• T("Date tag", minutesago, gte, 60) - 60 или более минут назад;
• T("Date tag", minutesago, lte, 1) - в течение последней минуты.

Пример оператора date

• T("Date tag", eq "2022-12-05 00:00:00")

Операторы для тегов типа Boolean

• eq - равно указанному значению
• noteq - не равно указанному значению
• any - устройства с любыми значениями, установленными для тега
• notset - устройства без установленного значения для тега

Пример синтаксиса для тегов типа Boolean

T("bool", eq, true)

Операторы для тегов типа Price

• eq - равно указанному значению
• noteq - не равно указанному значению
• lte - меньше или равно указанному значению
• gte - больше или равно указанному значению
• in - равно любому из указанных значений
• notin - не равно ни одному из указанных значений
• between - в указанном диапазоне
• any - устройства с любыми значениями, установленными для тега
• notset - устройства без установленного значения для тега

Пример синтаксиса для тегов типа Price

T("price", between, ["4.2", "6.9"])

Операторы для тегов типа Version

• eq - равно указанному значению
• noteq - не равно указанному значению
• lte - меньше или равно указанному значению
• gte - больше или равно указанному значению
• in - равно любому из указанных значений
• notin - не равно ни одному из указанных значений
• between - в указанном диапазоне
• any - устройства с любыми значениями, установленными для тега
• notset - устройства без установленного значения для тега

Пример синтаксиса для тегов типа Version

T("version", lte, "4.2")

Операторы условий для событий (Event)

Примечание

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

Количество событий

• count gte - устройства, вызвавшие событие более или ровно n раз
• count lte - устройства, вызвавшие событие менее или ровно n раз
• count eq - устройства, вызвавшие событие ровно n раз
• count noteq - устройства, вызвавшие событие любое количество раз, но не равное n

Пример синтаксиса для количества событий

Event("11111-11111", "Level reached", count gte 10) // 11111-11111 - это код приложения

Дата события

• 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 minutesago lte - дата вызова события меньше или равна указанному количеству минут до текущего момента
• date minutesago gte - дата вызова события больше или равна указанному количеству минут до текущего момента

Примеры синтаксиса для даты события

• Event("11111-11111", "Level reached", date gte "2022-01-01 01:02:03")
• Event("11111-11111", "Level reached", date in ["2022-01-01 01:02:03", "2022-01-01 02:03:04"])
• Event("11111-11111", "Level reached", date between "2022-01-01 01:02:03" "2022-01-01 02:03:04")
• Event("11111-11111", "Level reached", date minutesago lte 30) - события за последние 30 минут
• Event("11111-11111", "Level reached", date minutesago gte 60) - события 60+ минут назад

Платформы событий

Фильтрация событий по платформе, на которой они были вызваны.

• platforms - список платформ (например, [“ios”, “android”])

Пример синтаксиса для платформ событий

Event("11111-11111", "Level reached", platforms ["android", "ios"], count gte 5)

Атрибуты событий

Условия для событий могут фильтровать на основе значений атрибутов событий. Атрибуты поддерживают различные типы данных с соответствующими операторами.

Атрибуты событий типа Integer

• 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 - нет установленного значения для атрибута

Примеры синтаксиса для атрибутов типа Integer

• Event("11111-11111", "Purchase", attribute "amount" eq 42)
• Event("11111-11111", "Purchase", attribute "amount" between 10 100)
• Event("11111-11111", "Purchase", attribute "amount" in [10, 20, 30])

Атрибуты событий типа String

• 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 - нет установленного значения для атрибута

Примеры синтаксиса для атрибутов типа String

• Event("11111-11111", "Page View", attribute "url" startswith "https://example.com")
• Event("11111-11111", "Page View", attribute "url" endswith ".html")
• Event("11111-11111", "Page View", attribute "url" contains "/products/")
• Event("11111-11111", "Button Click", attribute "button_name" in ["submit", "cancel"])

Атрибуты событий типа Boolean

• attribute “name” eq - атрибут равен true или false
• attribute “name” noteq - атрибут не равен true или false

Пример синтаксиса для атрибутов типа Boolean

Event("11111-11111", "Feature Toggle", attribute "enabled" eq true)

Атрибуты событий типа Date

• 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” minutesago gte/lte - атрибут относительно прошедших минут
• attribute “name” any - любое значение, установленное для атрибута
• attribute “name” notset - нет установленного значения для атрибута

Примеры синтаксиса для атрибутов типа Date

• Event("11111-11111", "Subscription", attribute "start_date" eq "2022-01-01 01:02:03")
• Event("11111-11111", "Subscription", attribute "start_date" between "2022-01-01 00:00:00" "2022-12-31 23:59:59")
• Event("11111-11111", "Subscription", attribute "start_date" daysago lte 30) - в течение последних 30 дней
• Event("11111-11111", "Subscription", attribute "start_date" minutesago gte 60) - 60+ минут назад

Атрибуты событий типа Price

• 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 - нет установленного значения для атрибута

Пример синтаксиса для атрибутов типа Price

Event("11111-11111", "Purchase", attribute "total_price" between 10.00 50.00)

Атрибуты событий типа List

• attribute “name” in - атрибут содержит любое из указанных значений
• attribute “name” notin - атрибут не содержит ни одного из указанных значений
• attribute “name” any - любое значение, установленное для атрибута
• attribute “name” notset - нет установленного значения для атрибута

Пример синтаксиса для атрибутов типа List

Event("11111-11111", "Cart Update", attribute "product_ids" in ["prod-123", "prod-456"])

Дополнительные типы условий

Условие Geo

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

Синтаксис: Geo("<app-code>", <latitude>, <longitude>, <range-in-km>)

Пример синтаксиса Geo

Geo("11111-11111", 53.2734, -7.77832031, 100.05) - устройства в радиусе 100.05 км от координат

Условие BTTS

Нацеливание на устройства по их лучшему времени для отправки уведомлений (час дня, 0-23).

Операторы:

• any - установлено любое значение лучшего времени для отправки
• eq - точное совпадение часа
• noteq - не равно часу
• gte - час больше или равен
• lte - час меньше или равен

Примеры синтаксиса BTTS

• BTTS("11111-11111", eq 10) - устройства с лучшим временем в 10:00
• BTTS("11111-11111", gte 18) - устройства с лучшим временем с 18:00 и позже
• BTTS("11111-11111", any) - устройства с любым значением лучшего времени

Условие Updated

Фильтрация устройств по временной метке их последнего обновления.

Операторы:

• gte - обновлено после или в указанную дату
• lte - обновлено до или в указанную дату
• between - обновлено в диапазоне дат

Примеры синтаксиса Updated

• Updated("11111-11111", gte "2022-01-01 00:00:00") - устройства, обновленные после 1 января 2022 г.
• Updated("11111-11111", lte "2022-12-31 23:59:59") - устройства, обновленные до 31 декабря 2022 г.
• Updated("11111-11111", between "2022-01-01 00:00:00" "2022-12-31 23:59:59") - устройства, обновленные в 2022 году

Условие Segment

Ссылка на другой фильтр/сегмент по его коду.

Пример синтаксиса Segment

Segment("11111-11111", "22222-22222") - ссылка на фильтр с кодом “22222-22222”

Флаги наличия устройства в условии Application

Условия для приложений поддерживают дополнительные флаги для управления фильтрацией устройств и токенов:

• with_tokens - устройства с токенами push-уведомлений
• without_tokens - устройства без токенов push-уведомлений
• with_devices - пользователи с зарегистрированными устройствами
• without_devices - пользователи/профили без зарегистрированных устройств

Примеры синтаксиса флагов Application

• A("11111-11111", ["ios", "android"], [with_tokens]) - устройства с push-токенами
• A("11111-11111", ["ios", "android"], [without_tokens]) - устройства без push-токенов
• A("11111-11111", [], [with_devices]) - все устройства с записями об устройствах
• A("11111-11111", ["ios", "android"], [without_tokens, with_devices]) - устройства без токенов, но с записями об устройствах

Примеры фильтрующих выражений

Примечание

При написании JSON-запросов обязательно экранируйте кавычки (") и обратные слэши (\) с помощью обратного слэша (\). Пример запроса см. в /exportSegment.

Базовые примеры

1. Устройства iOS и Android с установленным приложением и с push-токенами:

A("11111-11111", ["ios","android"], [with_tokens])

2. Устройства iOS и Android с установленным приложением, но без push-токенов:

A("11111-11111", ["ios","android"], [without_tokens])

3. Устройства iOS и Android с установленным приложением, независимо от того, есть у них push-токены или нет:

A("11111-11111", ["ios","android"], [with_tokens, without_tokens])

4. Все подписчики приложения, которые что-то купили в приложении:

AT("11111-11111", "In-App Purchase", gte, 1)

Примечание

Пожалуйста, учтите, что теги, специфичные для приложения, обозначаются как AT вместо T, и должен быть указан код приложения.

Продвинутые примеры

5. Пользователи в Токио, которые открывали приложение за последние 7 дней:

T("City", eq, "Tokyo") * Event("11111-11111", "App Open", date daysago lte 7)

6. Пользователи, совершившие покупку на сумму более 50 долларов за последние 30 дней:

Event("11111-11111", "Purchase", attribute "total_price" gte 50.00, date daysago lte 30)

7. Пользователи, чьи имена начинаются на “J” или заканчиваются на “e”:

T("Name", startswith, "J") + T("Name", endswith, "e")

8. Активные пользователи iOS в радиусе 100 км от Нью-Йорка, которые не совершали покупок в последнее время:

A("11111-11111", ["ios"], [with_tokens]) * Geo("11111-11111", 40.7128, -74.0060, 100) \ Event("11111-11111", "Purchase", date daysago lte 30)

9. Пользователи с лучшим временем для отправки между 9 утра и 5 вечера:

BTTS("11111-11111", gte 9) * BTTS("11111-11111", lte 17)

10. Пользователи, которые вызвали определенное событие на Android или iOS за последний час:

Event("11111-11111", "Button Click", platforms ["android", "ios"], date minutesago lte 60)

11. Устройства, обновленные за последние 3 месяца, с версией приложения 4.2 или выше:

Updated("11111-11111", gte "2024-07-01 00:00:00") * AT("11111-11111", "App Version", gte, "4.2")