События и пользователи

Все отчёты ActionPulse построены на одном и том же: кто, что и когда сделал. Эта страница — про то, как это записывается.

Событие

Событие — факт: что-то произошло в определённый момент. order_created, signup_completed, pp.page_view.

Имя события подчиняется правилу ^[a-z0-9_.]{1,128}$: строчные латинские буквы, цифры, подчёркивание и точка, до 128 символов. Order_Created, заказ_создан и имя с пробелом будут отклонены с кодом invalid_event.

Практика, которая себя оправдывает:

• Существительное и глагол в прошедшем времени: order_created, signup_completed, subscription_started.
• Одно имя на один смысл. checkout_started и begin_checkout в одном проекте — источник расхождений в воронках.
• Различия описываются свойствами, а не именами. Вместо order_created_pro и order_created_basic — одно событие со свойством plan.

Свойства

Свойства (props) — детали события: план, сумма, способ оплаты, источник.

Ограничение	Значение
Количество свойств	до 64
Длина имени свойства	до 64 символов
Размер значения	до 8 КБ

Значением может быть строка, число, булево, вложенный объект или массив.

Стабильность типа важнее удобства: если total в одном месте число, а в другом строка "990", отчёты по нему начнут расходиться. Типы можно зафиксировать в реестре событий, и тогда несоответствие станет видимым нарушением, а не тихой проблемой.

Пользователи: user_id и anon_id

anon_id — анонимный идентификатор, который трекер создаёт сам для посетителя браузера.

user_id — ваш идентификатор пользователя из вашей же системы. Тот же, что в базе: он должен совпадать между браузером и бэкендом, иначе действия одного человека разъедутся на двух разных.

У события должен быть хотя бы один из них — иначе отказ missing_actor. Оба ограничены 256 символами.

identify

Как только вы узнали, кто перед вами, вызовите identify. С этого момента события связываются с user_id, а не только с анонимным идентификатором:

pp.identify('YOUR_USER_ID', { plan: 'pro' });

reset

При выходе из аккаунта вызывайте reset(), иначе следующий пользователь на том же устройстве продолжит историю предыдущего.

Сессия

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

event_id и повторы

event_id — UUID события. Он не обязателен: если его не прислать, сервер сгенерирует свой. Но тогда повтор запроса создаст второе событие.

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

Защита работает в пределах одного источника: одинаковый event_id из браузера и с сервера — это два разных события.

Время события

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

Кто что может отправлять

Право отправить событие определяется типом ключа. Это не настройка, а граница доверия.

Тип события	Браузерный токен	Серверный ключ
pp.* — встроенные	да	нет
Свои события	только имена из списка токена	да
Подтверждённые бизнес-события	нет	да

Встроенные события pp.*

Пространство pp.* принадлежит ActionPulse. Эти события формирует браузерный сбор, и через публичный track() их отправить нельзя:

Событие	Что означает
pp.page_view	просмотр страницы
pp.click	клик по элементу
pp.rage_click	серия быстрых кликов по одному месту
pp.dead_click	клик, после которого ничего не произошло
pp.hover_intent	намеренное наведение
pp.section_view	просмотр раздела страницы
pp.scroll_depth	глубина прокрутки
pp.form_field	взаимодействие с полем формы
pp.form_submit	отправка формы
pp.js_error	ошибка JavaScript
pp.web_vitals	метрики загрузки страницы

Свои события из браузера

Браузерный токен несёт собственный список разрешённых имён. Только что выпущенный токен разрешает одно имя — signup_completed. Остальные вернутся с credential_event_forbidden.

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

События только для сервера

Эти имена принимаются исключительно с серверным ключом:

registered, subscription_started, trial_started, trial_activated, trial_converted, trial_expired, payment_succeeded, payment_attached, order_created, first_order_created, order_paid, invoice_paid, refund.

Логика простая: браузер — недоверенный источник. Событие об оплате, пришедшее из браузера, ничего не подтверждает, потому что браузерный токен виден любому посетителю.

Реестр событий

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

Режим проверки задаётся на уровне проекта:

Режим	Что происходит
Выключена	события не проверяются по схеме
Мониторинг	нарушения записываются, событие принимается
Строгая	элемент с ошибкой отклоняется

Строгая проверка включается через подтверждение, в котором нужно ввести слово ENFORCE — это необратимо влияет на приём, поэтому сначала стоит побыть в режиме мониторинга и убедиться, что нарушений нет.

Отклонённое событие возвращается в rejected с кодом schema_violation и списком нарушений, а на экране проверки интеграции видно, что именно не сошлось.

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

Согласованность браузера и сервера

Одно и то же событие с двух сторон должно выглядеть одинаково:

• Одинаковое имя события.
• Одинаковый user_id.
• Одинаковые имена и типы свойств.

Хорошее разделение обязанностей:

Что	Откуда отправлять
Просмотры, клики, прокрутка	браузер, автоматически
Шаги воронки в интерфейсе	браузер
Регистрация подтверждена	сервер
Оплата, заказ, возврат	сервер
Выдача доступа, смена тарифа	сервер