План разметки событий

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

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

Сколько событий нужно

Начинайте не с экранов, а с вопросов, на которые нужен ответ. Один вопрос — одна метрика — одно-два события. Десяти-двадцати имён хватает большинству продуктов, и вот почему больше вредно.

• Полезная активность определяется ровно одним событием. В проекте выбирается единственное событие, от которого считаются DAU, WAU и MAU. Если событий сто, выбрать главное некому, и активность продолжает считаться «любое событие» — то есть ничего не означает.
• Различия — это свойства, а не имена. order_created_pro и order_created_basic дают две несравнимые серии. Одно событие order_created со свойством plan даёт разбивку в любом отчёте.
• Поведение в браузере уже собрано. Просмотры страниц, клики, проблемные клики, глубина прокрутки и работа с формами приходят встроенными событиями pp.*, если соответствующий сбор включён в настройках проекта — писать их руками не нужно. Что именно собирается — в статье поведение, формы и записи сессий.
• Каждое событие расходует квоту. Месячный лимит считает все принятые события, включая встроенные.
• Список имён для браузера фиксируется при выпуске токена. Браузерный токен несёт собственный список разрешённых имён (до 128), и он не редактируется: чтобы добавить имя, выпускают новый токен и меняют его в разметке.

Рабочий каркас, который закрывает почти все продуктовые вопросы:

Зачем	Пример имени	Откуда отправлять
Появился аккаунт	registered	сервер
Первое осмысленное действие	своё имя, например project_created	браузер или сервер
Ключевое повторяющееся действие	своё имя	браузер или сервер
Начало пути к деньгам	checkout_started	браузер
Деньги подтверждены	order_paid, payment_succeeded	только сервер
Деньги вернулись	refund	только сервер

Признак лишнего события простой: за месяц его не спросил ни один отчёт и ни одно оповещение. Такое событие можно перевести в «Устарело» и перестать отправлять.

Соглашение об именах

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

Правило	Так	Не так
Существительное и глагол в прошедшем времени	order_created	create_order, ordering
Одно имя на один смысл	checkout_started	checkout_started + begin_checkout
Значения — в свойства	order_created + plan	order_created_pro
Точка — только для своего пространства	billing.invoice_sent	pp.invoice_sent
Без версий и окружений в имени	order_created	order_created_v2, order_created_staging

Свойства, которые нужны почти всегда

revenue — платформенное свойство: число, рубли. Его разрешено класть в любое своё событие, и переопределить его своей схемой нельзя. Именно из props.revenue считаются блоки «Выручка за 30 дней» и «ARPU за 30 дней» на обзоре, метрики «Выручка, ₽» и «Средняя выручка на событие, ₽» в аналитике, режим «Потери, ₽» в воронке и выручка на пользователя в удержании. Без этого свойства денежные отчёты остаются пустыми.

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

Идентификаторы. У события должен быть user_id или anon_id, иначе отказ missing_actor. Один и тот же user_id по обе стороны — единственное, что связывает действия человека в браузере и на бэкенде.

Своё, по чему будете резать данные. Любое свойство появляется в отчётах как поле группировки prop:<имя>, поэтому имя и тип значения должны быть стабильными: если total в одном месте число, а в другом строка "990", отчёты по нему разойдутся.

А вот чего в свойствах быть не должно: приём заполняет это сам — по адресу страницы и по заголовкам запроса. Метки utm_source, utm_medium, utm_campaign разбираются из адреса страницы, тип устройства, операционная система и браузер — из User-Agent, страна — по адресу клиента. В отчётах все они уже есть как отдельные поля группировки наравне с url и referrer.

Чего не кладут в свойства

• Секреты. Пароли, токены, ключи, значения заголовков авторизации, cookie. Приём вырезает их безусловно — и по имени свойства, и по виду значения, на любой глубине вложенности.
• Персональные данные. E-mail, телефон, номер паспорта. Значение, похожее на них, заменяется на [redacted]; в адресе страницы такие параметры вырезаются точечно.
• Одноразовые ссылки. Приглашения, ссылки восстановления и подтверждения вырезаются из url и referrer.
• Большие объекты. До 64 свойств, значение до 8 КБ; превышение даёт too_many_props или prop_value_too_large. Корзину целиком в событие класть не надо — достаточно суммы и количества позиций.
• То, что меняется отдельно от факта. Текущий баланс или текущий статус подписки в событии соврут через день. Событие описывает момент.

Если поле в принципе не должно попадать в аналитику, отметьте его в схеме как запрещённое: тогда оно удаляется из события до записи, даже в режиме мониторинга, и порождает нарушение forbidden_property.

Почему пространство pp.* закрыто

Префикс pp. принадлежит ActionPulse. Это не вежливая просьба, а правило приёма:

• схемы событий pp.* выпускает платформа; создать, изменить или снять с поддержки такое событие через API нельзя — попытка возвращает 422;
• незнакомое имя в pp.* считается нарушением reserved_event, и в строгом режиме проверки такой элемент отклоняется;
• серверный ключ не может отправить имя из pp.* вообще — элемент отклоняется с credential_event_forbidden;
• в npm-пакете вызов track() с таким именем бросает TypeError ещё до отправки.

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

Как зафиксировать договорённость в реестре

Реестр событий — место, где план разметки перестаёт быть документом в вики и становится проверяемым контрактом. Зарегистрировать событие и выпустить версию схемы может участник с ролью analyst и выше; переключать режим проверки — admin и выше.

Что заполнить у события:

Поле	Зачем
Имя	неизменяемо; это то, что приходит в поле event
Название	человеческая подпись; без него событие нельзя выбрать определением полезной активности
Описание, Команда-владелец	чтобы через полгода было к кому прийти с вопросом
Источник	правило приёма, а не подпись — см. предупреждение ниже
Статус	черновик, активно или устарело

Версия схемы — это список ожидаемых свойств: до 64 штук, у каждого имя, тип (string, number, boolean, object, array, null), обязательность, классификация (обычное, возможные персональные данные, запрещённое) и пример. Пример должен быть синтетическим: копировать значения из настоящих событий в реестр нельзя, для этого в редакторе стоит отдельное предупреждение.

Порядок внедрения, который не ломает приём:

1. Зарегистрируйте события и версии схем, оставив режим проверки «Мониторинг» — он принимает всё и только записывает расхождения.
2. Отправьте события с реальным клиентом и откройте проверку интеграции: там видно, какие имена и свойства не совпали с договорённостью.
3. Исправьте расхождения — в коде или в схеме.
4. Когда нарушений в выбранном окне нет, включите «Строгую проверку». Переключение требует подтверждения: в поле нужно ввести слово ENFORCE.

Как менять разметку, не ломая отчёты

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

Новое свойство. Сначала опубликуйте новую версию схемы, потом выкатывайте код, который это свойство отправляет. В обратном порядке в строгом режиме получите unknown_property, а в мониторинге — поток нарушений.

Закрепите версию в клиенте. Поле schema_version: 0 означает «текущая версия из реестра»: публикация новой версии сразу меняет правила для уже задеплоенного кода. Если указать конкретный номер, клиент продолжит проверяться по нему, и вы сможете обновлять реестр и код независимо. Номер, которого в реестре нет, даёт нарушение schema_version_unknown.

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

Не удаляйте свойство, пока его кто-то отправляет. Свойство, которого нет в версии схемы, — это unknown_property. Сначала уберите отправку, потом свойство из схемы.

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

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

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

Чек-лист перед первой отправкой

1. Список событий — не больше двадцати, у каждого есть вопрос, на который оно отвечает.
2. Выбрано событие полезной активности, и у него заполнено «Название».
3. Имена проверены глазами на соответствие ^[a-z0-9_.]{1,128}$ и на дубли по смыслу.
4. Денежные события отправляются только с бэкенда и несут revenue.
5. У каждого события есть версия схемы, а у свойств — типы и классификация.
6. В свойствах нет ни секретов, ни персональных данных.
7. Режим проверки — «Мониторинг», и кто-то назначен смотреть нарушения на первой неделе.
8. Список разрешённых имён у браузерного токена совпадает с планом.