Свои события

Кроме событий сессий, приложение может отправлять свои события: purchase, note_created, paywall_shown. Своё событие — обычное событие в том же батче с именем на ваш выбор и, при желании, объектом properties. Сервер хранит и то и другое, а видно их на вкладке «События» дашборда, на странице профиля и в Read API.

Свои события происходят внутри сессии: отправляйте их между session_start и session_end с тем же session_id. session_id обязателен для каждого события, в том числе для своих.

Отправка событияСкопировать ссылку на раздел

Один батч с сессией и событием purchase с тремя свойствами:

NOW=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
INSTALL=$(uuidgen | tr A-Z a-z)
SESSION=$(uuidgen | tr A-Z a-z)
curl -sS https://i.analytics.example.com/v1/events \
  -H "Content-Type: application/json" \
  -H "X-App-Key: $AM_PK" \
  --data-binary @- <<JSON
{
  "sent_at": "$NOW",
  "context": { "platform": "server", "environment": "development", "ip": "none" },
  "events": [
    {
      "insert_id": "$(uuidgen | tr A-Z a-z)",
      "name": "session_start",
      "timestamp": "$NOW",
      "install_id": "$INSTALL",
      "session_id": "$SESSION"
    },
    {
      "insert_id": "$(uuidgen | tr A-Z a-z)",
      "name": "purchase",
      "timestamp": "$NOW",
      "install_id": "$INSTALL",
      "session_id": "$SESSION",
      "properties": { "plan": "pro", "amount": 12.5, "trial": false }
    },
    {
      "insert_id": "$(uuidgen | tr A-Z a-z)",
      "name": "session_end",
      "timestamp": "$NOW",
      "install_id": "$INSTALL",
      "session_id": "$SESSION",
      "duration_ms": 4200
    }
  ]
}
JSON

Ответ такой же, как для событий сессий: в accepted — число принятых событий, отклонённые приходят с кодом в rejected.

{ "accepted": 3, "rejected": [], "warnings": [], "server_time": "2026-10-14T09:15:02.318Z" }

Свои события несут те же поля, что и события сессий: insert_id, timestamp, install_id, user_id и context. Они идут через ту же офлайн-очередь и те же повторы; см. Время и офлайн-очередь и Ошибки и повторы.

Имена событийСкопировать ссылку на раздел

Имя — строка, подходящая под ^[a-z][a-z0-9_]{0,63}$: строчные латинские буквы, цифры и подчёркивания, первой идёт буква, не длиннее 64 символов. Называйте событие действием и не меняйте имя: переименованное событие начинает в отчётах новый ряд.

Зарезервированные имена. Системные события session_start и session_end описывают сессии. Любое другое имя с префиксом session_ зарезервировано, чтобы новые системные события можно было добавить, не столкнувшись с вашими. Имя не по шаблону или зарезервированное отклоняется кодом unknown_event_name, остальные события батча принимаются.

Число разных имён на приложение не ограничено, но вкладка «События» показывает первые 500 имён периода. Не собирайте имена из значений (opened_note_4821): значение кладите в свойство.

СвойстваСкопировать ссылку на раздел

properties — необязательный объект пар «ключ — значение», который описывает событие.

Значения хранятся строками: отчёты разбивают событие по тексту значения.

Строки хранятся как есть, без обрезки пробелов. Числа записываются в кратчайшей десятичной форме. Целые больше 2^53 теряют точность, потому что числа JSON читаются как 64-битные с плавающей точкой; такие значения отправляйте строкой. Число за пределами диапазона, например 1e400, отклоняется кодом invalid_field. Отчёты считают события и людей по каждому значению и не складывают числа, поэтому amount виден как разбивка по значениям, а не как сумма выручки.

Свойства разрешены и у session_start, и у session_end. Они хранятся, но отчёты сессий их не читают.

Свойства проверяются по ключам в том порядке, в каком они стоят в запросе, и первое нарушение отклоняет событие целиком. Если ключ в JSON-объекте повторяется, побеждает последнее значение.

Что не отправлятьСкопировать ссылку на раздел

Не кладите в свойства персональные данные: адреса почты, телефоны, имена, адреса проживания. Строковое значение, похожее на адрес почты или телефон, отклоняет событие кодом property_looks_like_pii. Событие отклоняется целиком, а не сохраняется без свойства: так утечка сразу видна в вашей интеграции, а не через месяцы в отчёте. В образце отклонённого события на вкладке «Интеграция» такое значение заменено на [redacted].

Проверка ловит только очевидные форматы. Передавайте непрозрачные идентификаторы (plan_id, order_id) и категории (source: "voice"), а всё, что опознаёт человека, держите вне свойств.

{
  "index": 1,
  "insert_id": "0199d6c1-0000-7000-8000-000000000007",
  "code": "property_looks_like_pii",
  "field": "events[1].properties.email",
  "message": "…",
  "retryable": false
}

ОтказыСкопировать ссылку на раздел

Отклонённое событие не влияет на остальные события батча. Все отказы — retryable: false: повтор того же события даст тот же ответ, поэтому отбросьте его и исправьте клиент.

Все коды описаны в Ошибках и повторах.

Где видны событияСкопировать ссылку на раздел

• Вкладка «События». Список своих событий периода с числом событий, людей и изменением к прошлому периоду. На странице события — график по времени, итоги и разбивка по значениям выбранного свойства. Вкладка показывает имена, у которых есть события в выбранном периоде; при включённом сравнении остаются и имена, у которых события были в прошлом периоде, а сейчас их нет (0, −100%). Вкладка следует переключателю Окружение: по умолчанию production, development — после переключения.
• Профиль. Свои события человека под его сессиями, со свойствами, платформой и версией приложения. В отличие от вкладки, профиль показывает события обоих окружений, а события development помечены значком «development».
• Realtime. Своё событие появляется в ленте под собственным именем.
• Интеграция. Счётчик принятых включает свои события, а отказы видны с их кодами.
• Read API. listEvents, getEventReport, getEventBreakdown и listProfileEvents; см. Read API: обзор.

Системные события во вкладку «События» не входят: у сессий свои отчёты на вкладке «Аудитория». Запрос отчёта по session_start или session_end в Read API отвечает 404 event_not_found. Событие без вхождений за период — не ошибка: ответ 200 с нулями.

Влияние на другие метрики. Свои события не меняют определений существующих метрик:

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

События хранятся 25 месяцев, как и события сессий, а удаление данных человека стирает и его свои события.

Чек-листСкопировать ссылку на раздел

1. Отправляйте свои события внутри сессии: тот же session_id, что у session_start.
2. Берите стабильные имена в snake_case без префикса session_.
3. Значения кладите в свойства, а не в имена; тип свойства между релизами не меняйте.
4. Не отправляйте адреса почты, телефоны и другие персональные данные.
5. Разворачивайте установку, которая понимает свои события, раньше сборки приложения, которая их отправляет: старый ingest отклонит такие события кодом unknown_event_name, и они потеряются.