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

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

Не стоит путать свойства пользователя и свойства события. Свойства события отражают дополнительную информацию о событии (например, у события "Сделал заказ" могут быть свойства "Сумма", "Товары" и т.д.). Свойства пользователя отражают информацию о пользователе. Например, имя, 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
$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 Категории просмотренных товаров (список из названий категорий товаров)