Свойства пользователя

Здесь собрана различная информация о свойствах пользователя.

Не стоит путать свойства пользователя и свойства события. Свойства события отражают дополнительную информацию о событии (например, у события "Сделал заказ" могут быть свойства "Сумма", "Товары" и т.д.). Свойства пользователя отражают информацию о пользователе. Например, имя, email, количество заказов, сумма всех заказов и т.д.

Типы данных

Поддерживается пять типов данных:

число
строка
дата/время
логический (булев)
список

Числа могут быть только целыми в диапазоне -2^53 .. +2^53, или -9007199254740992 .. +9007199254740992.

Максимальная длина строки 255 символов.

Элементами списка могут быть только строки длиной до 255 символов (максимум 30 элементов в списке).

Дата/время в формате ISO 8601: YYYY-MM-DDTHH:MM:SS. Допускается сокращенный вариант: YYYY-MM-DD (в этом случае будет подставлено время 00:00:00).

Пример:

{
    value1: 145,
    value2: "Hello, world!",
    value3: true,
    value4: "2015-09-13T13:25:05",
    value5: ["element1", "element2", "element3"]
}

Формат установки свойств

Иногда простой установки свойств недостаточно. Например, если вы отслеживаете количество нажатий на кнопку, было бы удобно каждый раз увеличивать значение свойства на единицу (операция add).

Другой пример - вы хотите узнать, какой раздел пользователь посетил первым. Здесь свойство нужно записать только в том случае, если оно еще не установлено (операция set_once).

Сложный формат для установки свойств представляет собой массив из объектов. Каждый объект — атомарная операция над свойством. В объекте три поля: op — операция, key — имя свойства, value — значение Поддерживаются следующие операции:

update_or_create — наиболее часто используемый вариант. Если свойство уже существует, перезаписать
set_once — записать только если свойства не существует
add — добавить заданное значение к свойству (если свойства не существует, перед записью значения оно будет создано со значением 0)
delete — удалить свойство
append — добавить в список
union — добавить в список, если еще не добавлен
exclude — удалить из списка

Примеры:

[
    // Установить значение (если уже существует - обновить)
    {"op": "update_or_create", "key": "my_property", "value": "Hello"},

    // Установить только если свойство не задано
    {"op": "set_once", "key": "my_property", "value": "Hello"},

    // Инкремент, декремент, добавление и вычитание
    {"op": "add", "key": "my_property", "value": "1"},
    {"op": "add", "key": "my_property", "value": "-1"},
    {"op": "add", "key": "my_property", "value": "15"},
    {"op": "add", "key": "my_property", "value": "-53"},

    // Удалить свойство
    {"op": "delete", "key": "my_property", "value": "0"},

    // Добавить элемент в список
    {"op": "append", "key": "my_list_property", "value": "super-element"},

    // Добавить элемент в список только если его там еще нет ("добавить в множество")
    {"op": "union", "key": "my_list_property", "value": "super-element"},

    // Удалить элемент из списка
    {"op": "exclude", "key": "my_list_property", "value": "super-element"},
]

На данный момент максимальное количество элементов в списке — 30 элементов. Элементами списка могут быть только строки.

При использовании append элементы добавляются последовательно. Порядок будет сохранен. При добавлении в список 31-го элемента заранее неизвестно, будет ли добавлен новый элемент (и какой из элементов будет удален перед этим).

При использовании union порядок элементов не сохраняется. Если в списке уже 30 элементов, добавление не гарантируется. Однако, гарантируется, что одинаковых элементов в списке не будет.

Системные свойства пользователя

Все названия свойств, начинающиеся с символа $, считаются системными. Ваши собственные свойства не должны начинаться с символа $.

Разрешено изменять только 3 свойства: $name, $phone, $email. Все остальные системные свойства можно только читать.

Имя	Описание
`$name`	Имя
`$email`	Email
`$phone`	Телефон
`$last_seen`	Последняя активность, дата совершения последнего события
`$last_contacted`	Последний контакт, дата последнего ответа от пользователя или последней отправки сообщения пользователю (в том числе автосообщения)
`$last_reply`	Дата последнего ответа от пользователя
`$conversations_emails`	Количество диалогов по email
`$conversations_chats`	Количество диалогов с типом чат
`$conversations_popups`	Количество диалогов с типом поп-ап
`$sessions`	Количество сессий
`$user_id`	User ID
`$score`	Количество баллов (рейтинг)
`$initial_referrer`	Первый источник (реферрер)
`$initial_referrer_domain`	Первый источник (реферрер), но только домен
`$initial_utm_campaign`	Первая метка UTM Campaign
`$initial_utm_source`	Первая метка UTM Source
`$initial_utm_medium`	Первая метка UTM Medium
`$initial_utm_content`	Первая метка UTM Content
`$initial_utm_term`	Первая метка UTM Term
`$last_utm_campaign`	Последняя метка UTM Campaign
`$last_utm_source`	Последняя метка UTM Source
`$last_utm_medium`	Последняя метка UTM Medium
`$last_utm_content`	Последняя метка UTM Content
`$last_utm_term`	Последняя метка UTM Term
`$country`	Страна
`$region`	Регион
`$city`	Город
`$latitude`	Географическая широта
`$longitude`	Географическая долгота
`$email_unsubscribed`	Отписался от email
`$avatar`	Имя файла с аватаром. Аватарки пользователей лежат по адресу: `https://files.carrotquest.io/avatars-users/{{ $avatar }}`
`$social_vk`	URL страницы ВКонтакте
`$social_facebook`	URL страницы Facebook
`$social_fourqsuare`	URL страницы Foursquare
`$social_googleplus`	URL страницы Google+
`$social_pinterest`	URL страницы Pinterest
`$social_twitter`	URL страницы Twitter
`$social_skype`	Skype

Устаревшие deprecated свойства: $comment, $last_active_user, $online, $idle, $cluster_id, $app_uid, $uid, $identity.

После первого совершения события, у пользователя появляются три свойства, связанные с этим событием. Например, если событие имеет ID=123, появятся свойства:

Имя	Описание
`$event_123_count`	Сколько раз было совершено событие
`$event_123_first`	Дата, когда событие было совершено первый раз
`$event_123_last`	Дата, когда событие было совершено последний раз

Свойства для интернет-магазинов

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

Имя	Описание
`$cart_amount`	Сумма в корзине (целое число)
`$viewed_products`	Просмотренные товары (список из названий товаров)
`$cart_items`	Корзина (список из названий товаров)
`$last_order_status`	Статус последнего заказа
`$last_payment`	Сумма последнего заказа (целое число)
`$revenue`	Сумма всех заказов (целое число)
`$profit`	Доход с пользователя (целое число)
`$group`	Группа
`$discount`	Скидка (целое число)
`$orders_count`	Количество заказов (целое число)
`$ordered_items`	Заказанные товары (список из названий товаров)
`$ordered_categories`	Категории заказанных товаров (список из названий категорий товаров)
`$viewed_categories`	Категории просмотренных товаров (список из названий категорий товаров)