Словарь понятий

Одни и те же понятия встречаются в интерфейсе, в ответах приёма событий и в этой документации. Здесь они собраны в одном месте: определение в одну-три фразы и, где это полезно, ссылка на страницу, где понятие используется по делу. Термины даны в том виде, в котором они подписаны в кабинете.

Организация, проект, люди

Организация — верхний уровень: она владеет проектами, участниками и тарифом. Тариф, счета и месячная квота событий принадлежат организации, а не отдельному проекту. Роли участников тоже задаются на уровне организации и действуют во всех её проектах.

Проект — контейнер данных: события, ключи приёма, реестр событий, отчёты, сегменты и сводные панели живут внутри одного проекта и не пересекаются с другими. У проекта есть собственный часовой пояс — именно в нём отчёты считают календарные сутки, недели и месяцы. Разделяйте по проектам разные продукты, а не разные окружения одного продукта: события одного проекта не видны в отчётах другого.

Участник — человек с доступом к кабинету организации; в интерфейсе это раздел «Настройки» → «Команда» → «Участники». У участника ровно одна роль из четырёх: owner, admin, analyst, viewer (в порядке убывания прав). Роль читается заново на каждом запросе, поэтому её изменение и удаление участника действуют сразу.

Актор — субъект аналитики: тот, чьи действия считают отчёты. Идентификатор актора (actor_id) — это user_id, если он известен, иначе anon_id. В списке событий столбец с актором подписан «Посетитель», в списке записей действий — «Актор».

События и их данные

Событие — факт: что-то произошло в определённый момент времени. У события есть имя, время, актор и, при необходимости, свойства. Имя подчиняется правилу ^[a-z0-9_.]{1,128}$; несоответствие даёт отказ invalid_event. Подробно — в статье события и пользователи.

Именованное событие — событие, имя которого выбрали вы: order_created, signup_completed, plan_upgraded. Противоположность — встроенное событие, имя которого задаёт платформа. Чаще всего именованное событие отправляет ваш код — вызовом track() в браузере или запросом с бэкенда.

Встроенное событие — событие в пространстве pp.*, которое формирует браузерный сбор ActionPulse: pp.page_view, pp.click, pp.scroll_depth и другие. Пространство pp.* зарезервировано платформой: своё событие туда положить нельзя, а серверный ключ не может отправить такое имя вообще. Что именно собирается — в статье поведение, формы и записи сессий.

Свойство события (props) — деталь факта: план, сумма, способ оплаты, идентификатор заказа. Ограничения: до 64 свойств, имя до 64 символов, значение до 8 КБ. Свойства становятся доступны в отчётах как поле группировки prop:<имя>, поэтому имя и тип значения должны быть стабильными.

Окно приёма — интервал ±48 часов от текущего момента, в который должно попадать поле time события. Событие со временем вне окна не отклоняется: ему проставляется время приёма. Это защита от неверных часов на клиенте, но она же означает, что задним числом историю через обычный приём не загрузить — для этого есть загрузка данных.

Идентификаторы

anon_id — анонимный идентификатор посетителя: случайный UUID, который браузерный трекер создаёт сам и хранит в localStorage. Он относится к браузеру и устройству, а не к человеку.

user_id — ваш собственный идентификатор пользователя, тот же, что в вашей базе. Значение должно совпадать между браузером и бэкендом, иначе действия одного человека разъедутся на двух акторов. Ограничение — 256 символов; использовать e-mail или телефон не нужно, это персональные данные.

session_id — идентификатор непрерывного отрезка активности. Браузерный трекер ведёт его сам и начинает новый после 30 минут без событий; поле необязательное и для событий с бэкенда обычно не заполняется. Как один идентификатор превращается в другой — в статье идентификация пользователей.

event_id — UUID конкретного события. Поле необязательное: без него сервер сгенерирует свой, но тогда повтор запроса создаст второе событие. Задавайте event_id сами и используйте одно значение на все попытки отправки. Подробнее — доставка, повторы и дубли.

Договорённости о разметке

Реестр событий — раздел «Реестр событий» в проекте: список событий с владельцем, описанием, статусом (черновик, активно, устарело) и версиями схемы. Реестр — это договорённость команды о том, какие события существуют и какие у них свойства; события, которых в нём нет, всё равно принимаются, пока не включён строгий режим проверки. См. план разметки событий.

Версия схемы — неизменяемый список ожидаемых свойств события с типами, обязательностью и классификацией (обычное, возможные персональные данные, запрещённое). Версии нумеруются с единицы и после сохранения не меняются: изменение разметки — это всегда новая версия. Поле schema_version в событии выбирает версию, по которой его проверять; 0 означает текущую.

Режим проверки — настройка проекта: выключена, мониторинг или строгая. В мониторинге нарушения записываются, а событие принимается; в строгом режиме нарушивший элемент отклоняется с кодом schema_violation. Что при этом видно — проверка интеграции.

Анализ

Событие-якорь — событие, от которого отсчитывается анализ. В разных отчётах оно подписано по-своему: «Стартовое событие» в удержании, «Опорное событие» в путях пользователей, «Начало пути» в драйверах удержания, первый шаг в воронке. Смена якоря меняет состав рассматриваемых акторов, а не только числа.

Сегмент — сохранённое правило отбора аудитории, а не список людей. Правило живое: оно заново применяется при каждом запуске отчёта, поэтому изменение сегмента меняет все отчёты, которые на него ссылаются. Отдельной страницы сегментов нет — ими управляют внутри конструктора фильтров любого отчёта, см. сегменты, отчёты и пути.

Отчёт — сохранённая конфигурация одного из шести типов: «Воронка», «Удержание», «Аналитика», «Пути пользователей», «Расширенный анализ», «Запрос к данным». Отчёт хранит настройки, а не результат: числа считаются заново при каждом открытии. Состояние конструктора целиком лежит в адресе страницы, поэтому ссылкой можно поделиться и без сохранения.

Сводная панель — набор «блоков» на общей сетке; каждый блок показывает результат сохранённого отчёта. Блокам можно задать автообновление, а саму панель открыть в ТВ-режиме на отдельном экране. Удаление панели не удаляет отчёты, удаление отчёта убирает его блоки с панелей.

Запись сессии — воспроизведение действий одного посетителя в браузере; в интерфейсе раздел называется «Записи действий». Значения полей ввода и — в строгом режиме приватности — текст страницы маскируются, элементы с атрибутом data-pp-block в запись не попадают вовсе, а каждый просмотр записи фиксируется в журнале аудита.

Доступ

Ключ приёма — то, чем подписывается отправка событий. Основных типа два: браузерный токен pp_bt_… (публичный, виден любому посетителю, ограничен списком разрешённых origin и списком имён событий) и серверный ключ pp_sk_… (секретный, только для бэкенда). Есть ещё устаревший совместимый ключ pp_wk_…, который совмещает оба набора прав и остаётся только для миграции. Ключи принадлежат проекту, выпускаются в его настройках и показываются один раз. См. типы ключей приёма.

Токен доступа — короткоживущий bearer-токен для основного API /api/v1, которым работает кабинет. Он выдаётся при входе, живёт 15 минут и обновляется отдельным запросом. Это не ключ приёма: токеном доступа события не отправляют, а ключом приёма отчёты не читают. См. справочник API.

Тариф и лимиты

Тариф — план обслуживания организации: Start, Growth или Scale. Тариф задаёт месячную квоту событий, срок хранения событий (от 6 месяцев до 25 месяцев в зависимости от плана) и доступ к части возможностей. Актуальные условия — на странице тарифов.

Квота — месячный лимит принятых событий по тарифу, от 20 млн событий до 1 млрд событий в зависимости от плана. В интерфейсе он подписан «Квота событий». По достижении лимита приём продолжается; когда объём доходит до 120 процентов от лимита, приём приостанавливается и отвечает 429 с кодом quota_exceeded. Встроенные события pp.* тоже расходуют квоту.

Что дальше

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