# События и метрики Этот справочник объясняет статистику ShopStory и её связь с аналитикой магазина. Настройка отправки описана отдельно: [Web tracking]() и [Mobile tracking](). ## Сначала выберите измеряемое действие | Метрика | Что считается | Ограничение | | --- | --- | --- | | Показ mini-player | Событие показа SDK-виджета | Не равно загрузке PDP или просмотру видео; повторные посещения могут дать новые показы | | Открытие из mini-player | Переход из виджета в player | Не подтверждает начало воспроизведения или просмотр до конца | | Просмотр VOD, first-party | Принятое событие просмотра от web-player | Событие отправляется по таймеру через 5 секунд после первого старта записи; это не определение уникального человека | | Время просмотра, first-party | Сумма принятых от player частей времени в секундах | Это данные телеметрии; потеря последнего запроса может уменьшить итог | | Переход к товару | Клик по фото или названию товара | Не является кликом «Купить» или подтверждённой корзиной | | Buy intent | Клик по кнопке «Купить» в ShopStory | Учитывается до результата Cart API, включая последующий отказ | | Сумма по Buy intent | Сумма доступных доверенных цен каталога для учтённых кликов | Не является суммой подтверждённых корзин, заказов или оплат | | Подтверждённое добавление | Cart API магазина подтвердил изменение корзины | Не подтверждает заказ или оплату | | Заказ / оплата / возврат | Соответствующее подтверждение системы магазина | Требуют собственных событий и покрытия этих этапов | Порог first-party VOD относится к таймеру web-player, а не к проценту просмотренного видео. Он не задаёт правила метрик видеопровайдера и live-эфира. Для live используются отдельные события подключения и активности; не объединяйте их с VOD без указания базиса. ## Источники VOD-метрик В отчёте могут использоваться данные видеопровайдера или first-party счётчики ShopStory. Их определения и покрытие могут различаться. Перед сравнением отчётов уточните источник, период и доступность каждого показателя. Если данных для расчёта нет, сохраняйте состояние «недоступно». Отсутствие данных не равно нулю: значение `0` можно трактовать как отсутствие просмотров только при подтверждённой доступности метрики за выбранный период. Справочник описывает метрики кабинета ShopStory. [Public API]() не предоставляет endpoint статистики. Покрытие метрик зависит от проекта и источника данных. ### Зрители и уникальность First-party счётчик увеличивается вместе с принятым событием просмотра. Он не вычисляет число различных покупателей или устройств. Число просмотров само по себе не подтверждает число уникальных зрителей. Для данных видеопровайдера проверьте его определение уникальности. Сумма уникальных значений по разным стримам не является числом уникальных людей по проекту. Не заменяйте недоступных зрителей числом просмотров. Определение distinct viewers и доступность исторических данных уточните для конкретного отчёта. ## Коэффициенты в детальной карточке Для отдельных вкладок live и VOD текущая карточка кабинета использует следующие расчёты: | Показатель | Расчёт | Как трактовать | | --- | --- | --- | | CTR товара | Переходы к товарам / просмотры × 100% | Отношение событий перехода к просмотрам выбранной вкладки | | Конверсия в Buy intent | Клики «Купить» / просмотры × 100% | Не конверсия в оплаченный заказ | | Среднее время live | Время live в секундах / live views | Среднее на базе live-счётчика | | Среднее время VOD | Время VOD в секундах / показатель зрителей VOD | Секунды; используйте показатели одного отчёта. Знаменатель зависит от источника и не всегда означает distinct viewers | При недоступном показателе или нулевом знаменателе коэффициент не определён. Не подставляйте `0%` или нулевую длительность вместо отсутствующих данных. Повторные переходы и клики одного человека остаются отдельными действиями; эти отношения не являются долями уникальных покупателей. Для общего live + VOD отчёта сначала проверьте состав итогов и базис каждой части. Не усредняйте проценты двух вкладок арифметически: нужны исходные числители и знаменатели за одинаковый период. ## События и callbacks События статистики ShopStory формируются player автоматически. Они не являются callback API для сайта или приложения. Не отправляйте их вручную из обработчиков корзины: это может дублировать данные. Для обработки действий пользователя используйте публичные контракты своей платформы: [Web SDK](), [native iOS]() или [Flutter](). Отправку событий в аналитику магазина настройте по руководствам [Web tracking]() и [Mobile tracking](). ### Поля и идентификаторы | Поле | Назначение | Правило интеграции | | --- | --- | --- | | `applicationId` | Проект ShopStory | Не доказывает полномочия на изменение корзины | | `streamId` | Эфир или запись | Не подставляйте ID другого проекта | | `feedProductId` | Товарный ID клиента | Строка с сохранением ведущих нулей; используйте для native routing | | `productId` | Внутренний ID ShopStory в соответствующем контракте | Не заменяет `feedProductId` | | Cart operation ID | Операция корзины магазина | Создаёт и дедуплицирует commerce-система; это отдельная идентичность | | `transaction_id` | Заказ в аналитике магазина | Используйте согласованный ID заказа, без email и телефона | Совпадение названия поля не означает совпадение схемы двух систем. [Таблица идентификаторов]() объясняет их назначение. ## Цена, количество и деньги Сумма по Buy intent рассчитывается по доступным ценам каталога. Если цена неизвестна, счётчик кликов может вырасти без денежной суммы. Цена не подтверждает фактические условия покупателя, выбранный SKU или результат Cart API. Для E-commerce аналитики магазина берите товар, количество, скидки, сумму и валюту из подтверждённой операции магазина. Единицу товара, строку корзины и весь заказ учитывайте раздельно. Не учитывайте подтверждённое добавление как ещё один клик «Купить». Пример на синтетических данных: 10 кликов «Купить» при цене каталога 1 000 ₽ дают сумму намерений 10 000 ₽. Cart API мог подтвердить 6 добавлений. Эти значения не определяют число заказов и оплаченную выручку. ## Дополнительное наблюдение на сайте магазина Для согласованной интеграции SDK может наблюдать E-commerce события PDP и страницы заказа. Эти события подключаются для проекта отдельно: | Событие | Подтверждение | Граница | | --- | --- | --- | | Просмотр PDP | На PDP обнаружено подходящее товарное событие магазина | Не доказывает показ mini-player | | Добавление в корзину | Обнаружено событие добавления от магазина | Само по себе не доказывает предшествующий просмотр ShopStory | | Оформление заказа | Обнаружено событие заказа магазина | Требует покрытия страницы заказа; не доказывает оплату | Связь с конкретным просмотром должна подтверждаться сохранённым контекстом и проверкой проекта, стрима и товара. Обычную органическую корзину нельзя автоматически относить к видео. UTM описывает источник перехода, но не заменяет эту проверку и не доказывает причинный эффект. ## Сверка двух отчётов 1. Зафиксируйте одинаковые проект, стримы, период и часовой пояс. 2. Назовите событие: shown, opened, Buy intent, cart add, заказ или оплата. 3. Укажите источник VOD-метрик и доступность каждого показателя. Не объединяйте несовместимые источники в один временной ряд. 4. Сравните единицы: события, товары, quantity, секунды, денежная сумма и валюта. 5. Проверьте покрытие страниц, consent, блокировщики, единственного отправителя и повторную доставку. 6. Найдите один тестовый путь и проследите его до отчёта целевой системы. Объекта в `dataLayer` недостаточно для подтверждения доставки. Универсальная задержка обновления отчётов не гарантируется. Момент появления данных зависит от принятого события, источника и целевой системы аналитики. Для проверки используйте тестовый период и время фактической отправки. Практический пример: [подтверждённая корзина и GA4](). Если значения не сходятся, используйте [диагностику аналитики]().