Поля

Документация полей описывает общие envelope, session, page, mapping, transport, rejection, derived и snapshot поля, которые используются в source-событиях, server-derived строках, rejected строках, transport batches и ссылках admin live-debug.

Группы полей

• Envelope: event identity, protocol, timestamp, ordering, and event type.
• Session/page context: anonymous session, tab, page instance, sanitized path, and coarse device/context fields.
• Mapping context: page, block, element, group, status, confidence, and compiled mapping version.
• Attribution context: allowlisted or hashed traffic-source fields only.
• Transport/rejection: accepted/rejected counts, retry/error/reason fields, and safe diagnostics.
• Derived/snapshot: derived type, source event reference, snapshot version, and status.

Контракт ссылок из админки

Live-debug rows expose field docs as anchors such as /fields#event-type with _ replaced by -. If a field is not documented here, admin rows should not render it as a docs link.

event-id

Группа: Envelope
Где используется: Все frontend events
Обязательность: Обязательно
Формат: evt_<random/uuid>

Уникальный ID для дедупликации.

Поведение при ошибке: Если нет — server rejects or generates rejected_id.

Приватность: Без ПДн.

batch-id

Группа: Envelope
Где используется: transport, source, rejected, derived rows
Обязательность: Required in storage
Формат: batch_<random/uuid>

Transport batch identifier used to connect source, rejected, transport, and derived rows.

Поведение при ошибке: Generate server-side for rejected rows when the client batch id is missing.

Приватность: No PII.

site-id

Группа: Context
Где используется: backend/admin/debug tables
Обязательность: Required in storage
Формат: UUID

Internal site UUID used to partition events and configs.

Поведение при ошибке: Reject or ignore writes without a valid site context.

Приватность: Internal only; not a browser identifier.

session-id

Группа: Session
Где используется: Все события
Обязательность: Обязательно
Формат: sess_<random>

Собирает события в один визит.

Поведение при ошибке: Если нет — создать новый на клиенте; если не получилось — reject.

Приватность: Не ПДн, random.

tab-id

Группа: Session
Где используется: Все события
Обязательность: Обязательно
Формат: tab_<random>

Отличает вкладки.

Поведение при ошибке: Если нет — создать новый.

Приватность: Не ПДн.

page-instance-id

Группа: Session
Где используется: Page-scoped events
Обязательность: Обязательно
Формат: pg_<random>

Отличает загрузки/SPA-страницы.

Поведение при ошибке: Если нет — создать новый при page_view.

Приватность: Не ПДн.

event-index

Группа: Envelope
Где используется: Все frontend events
Обязательность: Обязательно
Формат: integer, monotonic per session

Порядок событий в сессии.

Поведение при ошибке: Если нет — порядок по server_received_at, quality=low.

Приватность: Без ПДн.

event-type

Группа: Envelope
Где используется: Все frontend events
Обязательность: Обязательно
Формат: enum из листа 01

Тип события.

Поведение при ошибке: Если unknown — rejected event.

Приватность: Без ПДн.

protocol-version

Группа: Envelope
Где используется: Все frontend events
Обязательность: Обязательно
Формат: sf.events.v1

Версия протокола событий, чтобы сервер понимал схему.

Поведение при ошибке: Если нет — rejected event.

Приватность: Без ПДн.

event-ts

Группа: Envelope
Где используется: Все frontend events
Обязательность: Обязательно
Формат: ISO timestamp

Когда событие произошло в браузере.

Поведение при ошибке: Если нет — server_received_at, quality=low.

Приватность: Без ПДн.

received-at

Группа: Server timing
Где используется: ClickHouse rows
Обязательность: Server-filled
Формат: ISO timestamp

Server receive timestamp used for transport diagnostics and late-arrival ordering.

Поведение при ошибке: Fill on ingest; do not trust it as browser event time.

Приватность: No PII.

origin

Группа: Context
Где используется: ingestion, rejected, transport rows
Обязательность: Required for browser requests
Формат: HTTP(S) origin

Allowed origin that sent the SDK request.

Поведение при ошибке: Reject requests not in allowed origins.

Приватность: Origin only, no path/query.

path-sanitized

Группа: Page
Где используется: storage/live debug alias for page_path_sanitized
Обязательность: Required for page context
Формат: path without query/hash

Stored sanitized path used by ClickHouse and live debug.

Поведение при ошибке: Используйте unknown, если parsing не удался; query никогда не включайте.

Приватность: Raw URL/query not allowed.

page-code

Группа: Mapping
Где используется: События с context
Обязательность: Желательно
Формат: code из pageTags или unknown

Тип страницы из mapping config.

Поведение при ошибке: Если не найден — unknown.

Приватность: Без DOM/PII.

block-code

Группа: Mapping
Где используется: Click/visibility/forms
Обязательность: Опционально
Формат: code из blockTags или unknown

Смысловой блок, где произошло событие.

Поведение при ошибке: Если не найден — unknown.

Приватность: Без DOM/PII.

element-code

Группа: Mapping
Где используется: Click/forms/hover
Обязательность: Опционально
Формат: code из elementTags или unknown

Смысловой элемент.

Поведение при ошибке: Если не найден — unknown.

Приватность: Без DOM/PII.

group-code

Группа: Mapping
Где используется: Groups/clicks/visibility
Обязательность: Опционально
Формат: code из repeated group config

Повторяющийся объект: карточка/строка/результат.

Поведение при ошибке: Если не найден — omit/unknown.

Приватность: Без DOM/PII.

mapping-status

Группа: Mapping
Где используется: Все mapped events
Обязательность: Обязательно при mapping
Формат: applied,suspect,unknown,not_available

Качество применения разметки.

Поведение при ошибке: Если нет — unknown.

Приватность: Без DOM/PII.

mapping-confidence

Группа: Mapping
Где используется: Все mapped events
Обязательность: Желательно
Формат: 0.0-1.0

Уверенность сопоставления.

Поведение при ошибке: Если не считали — null.

Приватность: Без DOM/PII.

payload-json

Группа: Payload
Где используется: source and derived rows
Обязательность: Required in storage
Формат: JSON object

Sanitized event or derived payload.

Поведение при ошибке: Reject unsafe payloads; keep only safe JSON.

Приватность: No raw PII, DOM, cookies, query, or form values.

token-prefix

Группа: Diagnostics
Где используется: rejected/transport rows
Обязательность: Server-filled
Формат: short non-secret prefix

Identifies token family without exposing the token.

Поведение при ошибке: Never expose full token; prefix only.

Приватность: Non-secret prefix only.

reason-code

Группа: Rejection
Где используется: sf_rejected_events
Обязательность: Required for rejected rows
Формат: safe enum/string

Why an event or batch was rejected.

Поведение при ошибке: Use a stable safe reason code.

Приватность: No raw values or exception text.

safe-detail

Группа: Diagnostics
Где используется: rejected/transport rows
Обязательность: Optional
Формат: short safe string

Safe operator detail that explains a rejection or transport issue.

Поведение при ошибке: Drop details that contain values or secrets.

Приватность: Safe detail only.

payload-shape-json

Группа: Rejection
Где используется: sf_rejected_events
Обязательность: Required for rejected payloads
Формат: JSON shape object

Shape-only diagnostic for unsafe payloads.

Поведение при ошибке: Store keys/types only; never values.

Приватность: Payload shape only.

accepted-count

Группа: Transport
Где используется: sf_transport_batches
Обязательность: Server-filled
Формат: integer

Принятые source-события в batch.

Поведение при ошибке: Set to 0 when the whole batch is rejected.

Приватность: Aggregate count only.

rejected-count

Группа: Transport
Где используется: sf_transport_batches
Обязательность: Server-filled
Формат: integer

Отклоненные source-события в batch.

Поведение при ошибке: Increment for validation/privacy failures.

Приватность: Aggregate count only.

retry-count

Группа: Transport
Где используется: sf_transport_batches
Обязательность: Optional
Формат: integer

Client retry attempt count for delivery diagnostics.

Поведение при ошибке: Default to 0 when missing.

Приватность: No PII.

error-code

Группа: Transport
Где используется: sf_transport_batches
Обязательность: Optional
Формат: safe enum/string

Safe transport error classification.

Поведение при ошибке: Prefer known reason codes; no raw exception messages with secrets.

Приватность: Safe detail only.

source-event-id

Группа: Derived
Где используется: sf_server_derived_events
Обязательность: Optional
Формат: event id or empty

Source event that triggered a derived row when one-to-one.

Поведение при ошибке: Leave empty for session-wide aggregates.

Приватность: No PII.

derived-type

Группа: Derived
Где используется: sf_server_derived_events
Обязательность: Required
Формат: enum from sheet 02

Серверное событие/признак or feature type.

Поведение при ошибке: Отклоняйте unknown derived rows из SDK ingestion; server processor должен использовать catalog types.

Приватность: No PII.

mapping-version

Группа: Mapping
Где используется: events, derived rows, snapshots
Обязательность: Optional/required when mapping is active
Формат: compiled version id/hash

Mapping config version used to resolve codes.

Поведение при ошибке: Используйте пустое значение или unknown, если активного mapping нет.

Приватность: Config id only; no DOM/text.

snapshot-version

Группа: Session snapshot
Где используется: sf_session_snapshots
Обязательность: Server-filled
Формат: integer

Monotonic version of the session snapshot payload.

Поведение при ошибке: Увеличивайте счетчик по доступным source-событиям; если данных не хватает, оставляйте статус partial.

Приватность: No PII.

status

Группа: Generic status
Где используется: configs, snapshots, transport
Обязательность: Context-dependent
Формат: active/partial/expired/etc.

Operational state used by admin and QA surfaces.

Поведение при ошибке: Use safe enums, not free-form sensitive text.

Приватность: No PII.

visitor-id-hash

Группа: Session
Где используется: Повторные визиты
Обязательность: Опционально config
Формат: hash(random first-party id)

Позволяет считать возвраты 24ч/7д/30д.

Поведение при ошибке: Если нет — repeat features unavailable.

Приватность: Псевдонимный ID, включать config-ом.

ym-client-id-hash

Группа: Session
Где используется: Связка с Метрикой
Обязательность: Опционально config
Формат: hash(ym client id)

Позволяет связать с Метрикой, если разрешено.

Поведение при ошибке: Если нет — omit.

Приватность: Raw client_id не отправлять.

page-path-sanitized

Группа: Page
Где используется: page_view + context
Обязательность: Обязательно для page_view
Формат: /catalog/x/ без query/hash

Очищенный путь страницы.

Поведение при ошибке: Если URL не разобран — page_path_sanitized=unknown.

Приватность: Raw URL/query не отправлять.

page-hash

Группа: Page
Где используется: page_view + context
Обязательность: Желательно
Формат: hash(path_sanitized)

Группировка страниц без сырого URL.

Поведение при ошибке: Если не посчитался — omit.

Приватность: Hash не для ПДн query.

device-type

Группа: Device
Где используется: session/page context
Обязательность: Обязательно
Формат: desktop,mobile,tablet,unknown

Тип устройства.

Поведение при ошибке: Если не определён — unknown.

Приватность: Не fingerprint.

browser-family

Группа: Device
Где используется: session/page context
Обязательность: Желательно
Формат: Chrome,Safari,Firefox,Edge,Other

Грубый тип браузера.

Поведение при ошибке: Если не определён — unknown.

Приватность: Не отправлять полный UA.

viewport-w-bucket

Группа: Device
Где используется: page/session context
Обязательность: Желательно
Формат: число с округлением/bucket

Coarse viewport width bucket for visibility and layout behavior analysis.

Поведение при ошибке: Если нет — unknown.

Приватность: Не fingerprint с высокой точностью.

viewport-h-bucket

Группа: Device
Где используется: page/session context
Обязательность: Желательно
Формат: число с округлением/bucket

Coarse viewport height bucket for visibility and layout behavior analysis.

Поведение при ошибке: Если нет — unknown.

Приватность: Не fingerprint с высокой точностью.

utm-source

Группа: Attribution
Где используется: page_view
Обязательность: Опционально allowlist
Формат: raw allowlist или unknown

Allowlisted traffic source bucket.

Поведение при ошибке: Если нет — omit.

Приватность: Не отправлять весь query.

utm-medium

Группа: Attribution
Где используется: page_view
Обязательность: Опционально allowlist
Формат: raw allowlist или unknown

Allowlisted traffic medium bucket.

Поведение при ошибке: Если нет — omit.

Приватность: Не отправлять весь query.

utm-campaign-hash

Группа: Attribution
Где используется: page_view
Обязательность: Опционально
Формат: hash

Campaign hash without raw campaign text.

Поведение при ошибке: Если нет — omit.

Приватность: Raw campaign/term не отправлять.

utm-term-hash

Группа: Attribution
Где используется: page_view
Обязательность: Опционально
Формат: hash

Term hash without raw term text.

Поведение при ошибке: Если нет — omit.

Приватность: Raw campaign/term не отправлять.

connection-effective-type

Группа: Context
Где используется: session/page context
Обязательность: Опционально
Формат: 4g,3g,2g,slow-2g,unknown

Грубая скорость сети, если браузер даёт.

Поведение при ошибке: Если API недоступен — not_available.

Приватность: Не fingerprint.