Серверная передача конверсий в Яндекс Метрику: настройка и проверка

Браузерный счётчик видит действие только пока страница открыта и его код может выполниться. Но важная конверсия часто появляется позже: платёжная система подтверждает оплату webhook-запросом, менеджер квалифицирует лид в CRM, склад выдаёт заказ, а сервис активирует подписку после фоновой проверки. Если отправлять цель только из браузера, часть таких событий теряется или фиксируется раньше реального бизнес-результата.

Measurement Protocol Яндекс Метрики позволяет передавать взаимодействия напрямую с сервера по HTTP. Яндекс рекомендует использовать его вместе с обычным веб-счётчиком, а не вместо него [1]. Веб-счётчик формирует визит и ClientID, серверная часть добавляет подтверждённое действие, которое невозможно или ненадёжно измерять на странице.

Рабочая настройка — это не одиночный запрос к mc.yandex.ru. Нужны точное определение события, связь с ClientID, защита от повторов, очередь временных ошибок, безопасное хранение токена и контроль того, что данные появились в нужном счётчике.

Сначала выберите правильный механизм передачи

Когда подходит Measurement Protocol

Протокол полезен, когда событие достоверно возникает на сервере и должно быстро дополнить данные Метрики. Типичные сценарии — подтверждённая оплата, качественный лид, активация услуги, изменение статуса заказа или ecommerce-событие, которое браузер не отправил из-за блокировщика или закрытой вкладки.

Через протокол можно передавать просмотры страниц, JavaScript-цели, события электронной коммерции и параметры визитов [1]. Основной идентификатор — ClientID. Если событие удаётся связать с существующим визитом в допустимом временном окне, Метрика дополняет его серверными данными.

Когда лучше офлайн-конверсии или CRM-импорт

Measurement Protocol позволяет дополнить завершившийся веб-визит только в течение 12 часов [1]. Если продажа закрывается через несколько дней, важнее сохранить исходное время события и связать его с предшествующим визитом с помощью импорта офлайн-данных. Для офлайн-конверсий, звонков и заказов из CRM период дополнения составляет 21 день [2].

Если нужно передавать не только факт цели, но и жизненный цикл сделки, доход, себестоимость или статусы заказа, стоит рассмотреть импорт данных из CRM. Механизмы не конкурируют: быстрый серверный сигнал можно отправлять через Measurement Protocol, а поздний итог сделки — через подходящий формат офлайн-данных.

Опишите событие как бизнес-контракт

Привяжите цель к проверяемому статусу

Фраза «отправить конверсию после заказа» недостаточно точна. Нужно определить систему-источник и условие: заказ записан в базе, платёж имеет финальный успешный статус, менеджер перевёл лид в согласованный этап или услуга активирована. Событие должно возникать там, где этот факт уже нельзя перепутать с кликом или промежуточным экраном.

Для каждой цели зафиксируйте идентификатор события, номер счётчика, источник статуса, допустимую задержку, обязательные параметры и правило отмены. Если один и тот же статус может приходить несколькими путями, выберите единый слой, который решает, отправлять ли конверсию.

Задайте устойчивый ключ операции

Платёжные системы и очереди повторяют уведомления, а регламентное задание может обработать одну запись ещё раз. Поэтому каждой отправке нужен ключ идемпотентности, например payment_confirmed:ORDER-12345. До запроса к Метрике приложение проверяет, не завершалась ли уже эта операция успешно.

Ключ не заменяет ID цели или ID ecommerce-транзакции. Это внутреннее правило интеграции, которое защищает аналитику от повторов. В журнале полезно хранить ключ, время бизнес-события, ClientID, номер попытки, код ответа и итоговое состояние, но не секретный токен и не лишние персональные данные.

Сохраните ClientID рядом с заявкой или заказом

Получите идентификатор во время веб-визита

Метрика присваивает ClientID браузеру посетителя. Получить его можно методом getClientID [3]:

ym(XXXXXXXX, 'getClientID', function(clientID) { document.querySelector('[name=metrika_client_id]').value = clientID; });

Затем техническое поле передаётся вместе с формой или заказом и сохраняется на сервере. Нельзя пытаться получить ClientID впервые в момент webhook оплаты: браузерного контекста там уже нет. Также один человек в разных браузерах получит разные ClientID, поэтому этот идентификатор не следует считать постоянным ID клиента.

Проверьте всю цепочку хранения

Проследите путь от браузера до события: скрытое поле формы, API сайта, база, CRM, очередь и обработчик. Значение должно сохраняться без преобразований и не теряться при объединении дублей заявок. Если ClientID отсутствует, обработчик должен зафиксировать понятный статус, а не отправлять событие с выдуманным идентификатором.

После включения Measurement Protocol доступность истории ClientID расширяется постепенно: сначала один день, затем два и так далее до 21 дня [4]. Это важно учитывать при запуске — новый протокол не получает сразу всю прежнюю историю пользователей.

Включите протокол и защитите токен

Активируйте Measurement Protocol в нужном счётчике

В дополнительных настройках счётчика включите Measurement Protocol и получите авторизационный токен. Официальная документация допускает создание нескольких токенов [5], что удобно для разделения интеграций и безопасной ротации. Номер счётчика и токен относятся к конкретной конфигурации, поэтому тестовую и рабочую среды лучше не смешивать.

Токен должен храниться только на сервере: в защищённом хранилище секретов или переменной окружения с ограниченным доступом. Не помещайте его в JavaScript, репозиторий, URL клиентской страницы и открытый журнал. Предусмотрите замену токена без изменения бизнес-логики обработчика.

Формируйте запрос по официальной схеме

Данные отправляются POST- или GET-запросом на https://mc.yandex.ru/collect. Для обычной цели обязательны номер счётчика tid, ClientID cid, тип взаимодействия t=event, идентификатор цели ea и секретный токен ms. Время события передаётся параметром et; если его нет, используется время отправки [6].

Для ecommerce-покупки дополнительно используются действие pa=purchase, ID транзакции ti, доход tr и товарные параметры. Все значения должны быть URL-кодированы и переданы в UTF-8 [6]. Не копируйте демонстрационный URL как готовый production-код: формируйте параметры библиотекой HTTP-клиента и проверяйте обязательность полей для выбранного типа события.

Добавьте очередь, повторы и наблюдаемость

Не отправляйте событие прямо из критического запроса

Webhook оплаты или сохранение сделки не должны зависеть от доступности внешней аналитики. Надёжнее записать событие во внутреннюю таблицу или очередь в той же бизнес-транзакции, а отдельный обработчик отправит его в Метрику. Так временная ошибка не отменит платёж и не потеряет конверсию.

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

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

Успешный HTTP-ответ подтверждает приём запроса, но окончательная приёмка требует появления цели или ecommerce-события в счётчике. Справка сообщает, что данные Measurement Protocol записываются в счётчик в течение 20 минут [5]. Поэтому журнал должен сохранять технический ответ, а контрольный сценарий — включать последующую проверку отчёта.

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

Учитывайте временные окна и правила визитов

Дополнение существующего визита ограничено 12 часами

Событие можно добавить к завершившемуся веб-визиту, только если с момента его завершения прошло не более 12 часов [1]. Время et также нельзя передавать более чем на 12 часов назад [6]. Проверяйте часовой пояс, единицы timestamp и реальную задержку очереди: ошибка во времени способна сделать формально правильный запрос бесполезным.

Если подходящего визита нет или окно закрыто, одиночное событие не будет записано. Чтобы создать новый визит через Measurement Protocol, сначала передают t=pageview, затем связанные события [4]. Это создаёт новый визит с тем же ClientID, но не превращает его в старый исходный визит.

Для поздних событий выберите офлайн-передачу

Если важно дополнить именно более ранний визит, используйте офлайн-конверсии. Подготовленная запись содержит хотя бы один поддерживаемый идентификатор, Target и DateTime; после загрузки статус привязки можно проверить в отчёте «Офлайн-конверсии» [7]. Данные появляются в отчётах в течение нескольких часов, а причины непривязанных записей доступны отдельно.

ClientID обеспечивает наиболее точную привязку офлайн-данных и поддерживается для офлайн-конверсий, CRM и звонков [2]. PurchaseId полезен, когда нужно дополнить уже зафиксированную ecommerce-покупку, например информацией о выкупе. Выбор идентификатора должен быть частью архитектуры, а не решением после накопления неподписанных заказов.

Не передавайте идентификационные данные обычным событием

Условия Метрики запрещают передавать идентификационную информацию через обычные события и параметры, кроме функций, специально предназначенных для такой передачи [8]. Телефон, email, ФИО, паспортные и платёжные данные не должны попадать в ea, параметры визита, URL, заголовок страницы, UTM-метки и технические логи запроса.

Используйте ClientID и неперсональный внутренний ID операции. Если бизнесу нужен импорт email или телефона для сопоставления, применяйте предусмотренный Метрикой CRM-механизм и его правила нормализации, а не произвольный параметр Measurement Protocol. Доступ к токену, журналу и таблице связи ограничьте по ролям и срокам хранения.

Проведите контрольную приёмку

Проверьте обычное событие, дубль и временную ошибку

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

Затем повторите то же уведомление: новая конверсия не должна отправиться, а журнал должен зафиксировать отброшенный дубль. Наконец, имитируйте временную сетевую ошибку и подтвердите, что событие осталось в очереди, повторилось по правилу и не превратилось в две успешные отправки.

Зафиксируйте критерии готовности

• ClientID сохраняется вместе с каждой подходящей заявкой или покупкой и доходит до обработчика без изменения.
• Событие возникает только после точного серверного статуса, а не по клику пользователя.
• Токен хранится на сервере и может быть заменён без публикации в коде.
• Ключ идемпотентности защищает от повторных callback и ручного перезапуска задания.
• Очередь переживает временную недоступность Метрики и не блокирует основной бизнес-процесс.
• В журнале видны попытки и ответы, но нет секретов и лишних персональных данных.
• Контрольная конверсия появляется в нужном счётчике, а задержка укладывается в выбранный механизм и временное окно.

После приёмки сохраните карту полей, описание статуса, формат ключа, правила повторов и инструкцию ротации токена. Тогда следующую серверную цель можно добавить на той же основе, не создавая отдельный ненаблюдаемый скрипт.

Официальные источники

1. API Яндекс Метрики: использование Measurement Protocol.
2. Яндекс Метрика: импорт офлайн-данных.
3. Яндекс Метрика: метод getClientID.
4. Яндекс Метрика: настройка Measurement Protocol.
5. API Яндекс Метрики: параметры и примеры загрузки.
6. Яндекс Метрика: обработка офлайн-конверсий.
7. Яндекс Метрика: конфиденциальность данных.