Measurement Protocol для Яндекс Метрики

Друзья! Наконец-то (11 октября 2024 г.) в Яндекс Метрике появилась возможность отправлять данные о визите пользователя и связанных с ним событиях, совершаемых вне сайта, напрямую с вашего сервера на сервера Метрики посредством HTTP-запросов. Сделать это можно с помощью Measurement Protocol.

Введение

Если вы ранее работали с Google Analytics (версии 3 или 4), то уже слышали про такую технологию:

• Measurement Protocol (Universal Analytics);
• Measurement Protocol для Google Analytics 4;
• Параметры запроса Measurement Protocol v2 для Google Analytics 4.

Если нет, то самое время разобраться в этом, поскольку нововведение Яндекса очень сильно расширяет возможности сбора и анализа данных вашего счетчика Метрики.

Что такое Measurement Protocol?

Measurement Protocol (MP, протокол измерений, протокол передачи данных) - технология, которая позволяет с помощью специальной конструкции (HTTP-запросов) отправлять дополнительные данные о пользователе, его визитах или связанные с ними события в Яндекс Метрику даже в том случае, если они были совершены за пределами вашего сайта, с любого устройства, подключенного к Интернету.

Это означает, что благодаря протоколу передачи данных, вы можете значительно расширить сбор и анализ данных ваших пользователей, а именно:

• отправлять данные об офлайн-конверсиях в Яндекс Метрику (можно было делать и раньше, но только через предварительно подготовленный файл .csv и привязывать эти действия к ClientID, UserID, yclid или PurchaseId);
• связывать офлайн и онлайн-конверсии между собой;
• отслеживать клиентские и серверные взаимодействия.

Примеры использования

Пример №1. Офлайн-конверсии

Предположим, у вас есть интернет-магазин, и ваш клиент попросил доставку на дом с оплатой курьеру. После проведения транзакции данные попадают в вашу внутреннюю базу данных о заказах с измененным статусом (например, был В доставке, а теперь Оплачено). После этого вы можете отправить данные в Яндекс Метрику о совершенном действии (покупка). В случае, если пользователь позвонил вашему менеджеру и попросил отменить заказ, вы так же можете с помощью Measurement Protocol передать в Метрику данные об отмене/возврате, чтобы скорректировать статистику в отчетах. И пользователь, при этом, может не находиться на вашем сайте в этот момент.

Другой пример. Пользователь перешел на ваш сайт по рекламному объявлению из Яндекс Директа. Client ID и yclid при этом были записаны. Он делает заказ, но хочет оплатить его после получения. Данные по Client ID и yclid попадают в вашу базу данных / CRM-систему. Затем пользователь приезжает к вам в офис и делает покупку офлайн. С помощью Measurement Protocol можно передать конверсию в Яндекс Метрику после подтверждения заказа.

Пример №2. Отслеживание событий электронной торговли

Если пользователи не возвращаются на сайт после страницы эквайринга (редиректа на платежный шлюз для оплаты заказа, где человек вводит данные своей банковской карты) или когда счетчик не может зафиксировать данные по другим причинам, вы можете отправить дополнительное событие электронной торговли в Яндекс Метрику и учесть эту покупку.

Пример №3. Дополнительные данные по качеству лида

Благодаря новым возможностям Яндекс Метрики вы можете на каждом этапе сделки (если ваш проект/бизнес подразумевает это) отправлять дополнительную информацию о качестве лида/обращения (например - "холодный", "теплый", "горячий"). Это позволит вам в дальнейшем сегментировать пользователей по этим сведениям в Метрике, проводить глубокий анализ и детальнее прорабатывать персональные предложения, включая рекламные объявления.

Пример №4. Изменение статуса сделки

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

Для этого требуется ряд настроек, в числе которых:

• настройка уникального идентификатора пользователя (Client ID), извлечение этого значения из файла cookie _ym_uid;
• создание отдельного поля Client ID и сохранение его значения в лиде/сделке CRM;
• для каждого требуемого действия в CRM-системе сформировать свой http-запрос, который будет отправлять данные в Яндекс Метрику после его срабатывания;
• при изменении статуса сделки в CRM отправлять событие для конкретного пользователя в Яндекс Метрику.

Пример №5. Отслеживание действий как на стороне клиента, так и на стороне сервера

Если по каким-то причинам сбор данных пользователя ограничен на стороне клиента (например, из-за блокировщиков рекламы, установленных в браузере, или из-за настроек самих браузеров, включая системы интеллектуального отслеживания), с помощью Measurement Protocol вы сможете дополнить статистику в счетчике новыми данными, в случае, если они не были зафиксированы по описанным выше причинам.

Во всех вышеперечисленных примерах так или иначе фигурирует Measurement Protocol. Протокол передачи данных не нужно использовать, если вы просто хотите отслеживать различные события, которые совершают пользователя на вашем сайте. Для этого достаточно настроенных целей через интерфейс, либо же с использованием систем управления тегами, например, Google Tag Manager. Measurement Protocol - это не замена, а дополнение к вашему сбору данных счетчиком Яндекс Метрики.

Остался нерешенным самый главный вопрос - а как Яндекс Метрика понимает какому конкретно пользователю записать отправляемое через Measurement Protocol событие? Ответ на него будет дан ниже.

Принцип работы

Основной идентификатор в Measurement Protocol, с помощью которого вы можете привязать офлайн-события к онлайн-данным вашего счетчика Яндекс Метрики - Client ID. Он позволяет связать передаваемые данные с историей и визитами пользователя на счетчике.

Этот уникальный идентификатор пользователя используется везде и вся, причем не только в Яндекс Метрике. Он так же является одним из ключевых способов идентификации данных в Google Analytics 4.

Client ID - это:

• возможность посмотреть данные конкретного посетителя (или группы пользователей);
• основной (но не единственный) идентификатор при построении сквозной аналитики;
• работа с параметрами посетителя;
• возможность загрузить дополнительные данные (офлайн-конверсии);
• помощь при отладке/настройке своих собственных отслеживаний.

В моем блоге на эту тему написано более 10+ материалов. Это действительно важно. Если вы до сих пор не разобрались в том, как Яндекс Метрика определяет отдельных пользователей и связывает с ними события, обязательно прочитайте нижеприведенные публикации. Без них вам будет трудно понять инструмент Measurement Protocol.

• ClientID в Яндекс Метрике
• 3 способа получения ClientID Яндекс Метрики с помощью Google Tag Manager
• Сквозная аналитика в Яндекс Метрике
• Кейс по настройке сквозной аналитики
• 1 Client ID - 2 разных профиля посетителя в Яндекс.Метрике. Как?
• Почему дата первого визита не равна метке ClientID в Яндекс Метрике?

И это только статьи по Яндекс Метрике. Такое же количество есть и для Google Analytics 4.

Итак, Client ID позволяет связать передаваемые данные с историей и визитами пользователя на счетчике. Это обязательный параметр в Measurement Protocol, без которого вы не сможете отправлять HTTP-запросы.

Данные, которые вы можете отправлять с помощью Measurement Protocol Яндекс Метрики:

• посещения страниц (событие pageview);
• Javascript-события;
• события электронной коммерции.

Как выглядит сетевой запрос Яндекс Метрики?

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

• перейдите на сайт, где установлен код счетчика Яндекс Метрики;
• в браузере откройте панель разработчика - вкладка Network / Сеть;
• в поисковой строке пропишите идентификатор своего счетчика Метрики;
• обновите страницу;

Если у вас активирована опция Вебвизор, карта скроллинга, аналитика форм, то таких строк с запросами может появиться несколько.

Посмотрите некоторых из них. В одном случае в строке Request URL вы увидите URL-адрес вида https://mc.yandex.ru/watch/{ID}... и набор большого количества идущих далее параметров:

. где {ID} - идентификатор счетчика Яндекс Метрика.

В другом - это может быть запрос от Вебвизора, содержащий в строке Request URL конструкцию https://mc.yandex.ru/webvisor/{ID}...

Параметров может быть много в запросе, состоят они из пар ключ=значение. Параметры разделяются символом «&». Все параметры пишутся в одну строку без пробелов.

Если выбрать сам запрос и перейти на вкладку Payload (Полезная нагрузка), то там вы увидите подробные сведения об этом запросе с разделением параметров на отдельные строки:

Вот пример полного запроса из скриншота выше:

Информация, передаваемая через этот запрос, позволяет Яндекс Метрике собирать данные о посещении пользователем страницы, включая данные о браузере, разрешении экрана, URL-адресе и заголовке страницы, а также данные, связанные с соблюдением GDPR и другими аспектами взаимодействия с пользователем (например, согласие на обработку данных и настройка конфиденциальности).

И такие запросы в браузере пользователя (и вашем) выполняются постоянно, по мере совершения тех или иных событий (просмотры страниц, JS-события, события электронной торговли и т.д.).

Передача данных Measurement Protocol

Процесс отправки данных в Яндекс Метрику с помощью Measurement Protocol состоит из:

• строки отправки (transport);
• строки набора данных с параметрами (payload data)

Cтрока отправки (transport) указывает куда и как отправлять данные. Пример:

Доступна отправка POST или GET-запросами.

Строка набора данных (payload data) содержит набор параметров, передаваемых в запросе. Пример:

Каждый параметр в запросе представляет собой пару ключ=значение. Например:

То, что идет до знака равно - это ключ, после - значение. Например, ключами могут быть:

• tid - идентификатор счетчика Яндекс Метрики;
• cid - уникальный идентификатор пользователя (ClientID);
• t - тип взаимодействия;
• dr - реферер;
• dl - URL-адрес страницы;
• dt - заголовок страницы;
• et - время события в Timestamp;
• ms - секретный токен.

А их значения:

• tid = 5564333
• cid = 1710232430899999999
• t = pageview
• dr = https://yandex.ru
• dl = https://test.com
• dt = Test
• et = 1632467908
• ms = 01c0a669-d38c-4385-9d22-47cf894ed687

Есть обязательные параметры, которые зависят от типа взаимодействия, и дополнительные параметры, расширяющие возможности аналитики переданных данных. Все значения параметров должны быть URL-кодированы и закодированы в формате UTF-8. Все параметры пишутся в одну строку без пробелов.

Список поддерживаемых параметров, которые вы можете передавать в Measurement Protocol для Яндекс Метрики, доступен в официальной документации Яндекса.

Обязательными параметрами для отправки через Measurement Protocol являются:

• tid - идентификатор счетчика Яндекс Метрики;
• cid - уникальный идентификатор пользователя (ClientID);
• t - тип взаимодействия (просмотр страницы - pageview; Javascript-событие и события электронной коммерции - event);
• ms - секретный токен (генерируется при включении опции Measurement Protocol в интерфейсе Яндекс Метрики).

Далее, в зависимости от выбранного типа взаимодействия, обязательными являются следующие параметры.

Для события pageview (просмотр страницы):

• dr - реферер;
• dl - URL-адрес страницы;
• dt - заголовок страницы;

Для события event (событие) и событий электронной торговли (ecommerce):

• ea - название события/цели (обязательный для события event);
• pa - события электронной торговли (detail - просмотр информации; add - добавление в корзину; remove - удаление из корзины; purchase - покупка / обязательный для события event);
• ti - идентификатор транзакции (обязательный для события event и pa=purchase);
• tr - доход от транзакции (обязательный для события event и pa=purchase);
• tcc - купон транзакции (обязательный для события event и pa=purchase);
• pr<productIndex>id - код товара (обязательный для события event и pa!=null);
• pr<productIndex>nm - название товара (обязательный для события event и pa!=null);
• pr<productIndex>br - бренд товара (обязательный для события event и pa!=null);
• pr<productIndex>ca - категория товара (обязательный для события event и pa!=null);
• pr<productIndex>pr - цена товара (обязательный для события event и pa!=null);
• pr<productIndex>qt - количество единиц товара (обязательный для события event и pa!=null);
• pr<productIndex>va - разновидность товара (обязательный для события event и pa!=null);
• pr<productIndex>cc - код купона товара (обязательный для события event и pa!=null);
• pr<productIndex>ps - позиция товара (обязательный для события event и pa!=null).

Примечание: в productIndex указывать порядковый номер товара в списке

Помимо обязательных параметров, в Яндекс Метрике есть еще ряд необязательных, но не менее полезных параметров, которые вы можете отправить с запросом:

• sr - размер окна (формат для значения параметра - 1440x900x30);
• cu - валюта (поддерживается для целей с ценностью и для событий электронной торговли);
• ev - ценность цели (поддерживается при передаче целей, то есть когда используется ea);
• et - время события в Timestamp (если значение не передано - будет использовано время отправки данных. Допускается не более 12 часов назад от текущего времени);

Особенности Measurement Protocol

• через Measurement Protocol можно создать визит, либо дополнить существующий визит;
• для создания визита нужно обязательно указать ClientID пользователя;
• для формирования визита нужно передать как минимум один просмотр страницы (t=pageview) в начале визита;
• визиты формируются по тем же правилам и ограничениям, что и обычные визиты;
• данные можно отправить максимум на 12 часов назад от текущего времени. Если не отправлять параметр et - будет указано время отправки данных;
• обновить визит можно только в рамках тайм-аута визита, указанного в настройках счетчика, используя параметр et или отправляя данные без этого параметра в пределах тайм-аута визита. Если выйти за тайм-аут - начнется новый визит (после отправки pageview).

Ограничения Measurement Protocol

Создание новых визитов c помощью открывающего события pageview

Чтобы создать новый визит, вам необходимо отправить как минимум один запрос с просмотром страницы (t=pageview). Если вы отправляете события (например, события электронной коммерции или конверсии по JavaScript-целям), но они не могут быть привязаны к существующему визиту (из-за истечения 12 часов с момента его завершения или отсутствия визитов с переданным ClientID), данные не будут записаны. Чтобы избежать этого, сначала отправьте pageview для создания нового визита, а затем добавьте к нему нужные события.

Ограничение по времени на дополнение визитов

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

Если требуется передать данные для более старых визитов, Яндекс рекомендует использовать передачу офлайн-данных. Единственный способ записать данные через Measurement Protocol для пользователей, чьи визиты завершились более 12 часов назад - это создать новый визит с нужным ClientID и добавить в него необходимые события, которые будут связаны с этим пользователем.

В официальной справке Яндекса приведено наглядное изображение, демонстрирующее данное ограничение:

Тайм-аут визита вы можете посмотреть в настройках счетчика Яндекс Метрики:

Постепенная доступность ClientID для обогащения истории

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

Примеры передачи данных

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

Отправка просмотра

Достижение JS-цели order-success

Просмотр карточки товара Apple iPhone стоимостью 50000 с SKU 456

Добавление товара в корзину

Покупка товара

Покупка нескольких товаров

Теперь пошагово разберем отправку своего собственного HTTP-запроса. Для этого необходимо:

• активировать Measurement Protocol в настройках счетчика Яндекс Метрики;
• получить авторизационный токен;
• узнать/сохранить ClientID пользователя в том месте, откуда будут отправляться запросы;
• отправить запрос.

Рассмотрим каждый шаг подробнее.

Активация Measurement Protocol

Перейдите в интерфейс вашего счетчика Яндекс Метрики, откройте Настройки - Дополнительные настройки - Безопасность и использование данных и включите опцию Measurement Protocol:

Получение токена

Скопируйте токен, который был выпущен автоматически. Либо же добавьте новый токен, нажав на кнопку Добавить токен.

Его вы будете отправлять вместе с HTTP-запросом. Максимальное количество токенов на счетчик - 5.

Дополнительные материалы по токенам:

• Управление опцией и токенами
• Генерация дополнительных токенов
• Удаление токена

Сохранение ClientID пользователя

Как вы уже знаете, одним из обязательных параметров для отправки запроса через Measurement Protocol, является ClientID. Узнать свой уникальный идентификатор, привязанный к браузеру и устройству, можно с помощью этого руководства. Но что, если нам нужно не просто узнать его один раз, но и где-то сохранять для последующей автоматизации отправки офлайн-данных? Не будем же мы всегда вручную отправлять HTTP-запросы...

На мой взгляд, этот пункт является самым сложным, поскольку требует сторонней помощи (привлечение программиста или даже целой команды интеграторов). Как и в случае с настройкой сквозной аналитики, для автоматического! формирования запросов с помощью Measurement Protocol вам необходимо настроить получение уникального идентификатора пользователя Яндекс Метрики (Client ID) на сайте из файла cookie _ym_uid и отправлять его в CRM-систему, базу данных или другую конечную точку отдельным полем, чтобы при получении каких-либо обращений (заявок, звонков) с сайта в карточке клиента вы видели это значение:

Именно значение из поля _ym_uid является обязательным параметром в запросе Measurement Protocol. И его нужно обязательно сохранять для каждого пользователя/клиента, чтобы впоследствии автоматически подставлять его в сам HTTP-запрос. Разработчик может получить значение Client ID с помощью метода getClientID. Затем его следует сохранить в CRM. Подробнее об этом читайте в официальной справке Яндекса.

В качестве примера отправки запроса с помощью MP я буду использовать свой уникальный идентификатор пользователя, который извлек из браузера - 1729447244995188900:

Отправка HTTP-запроса

Все, что осталось сделать - это определиться с окончательным запросом для пользователя. В качестве примера я отправлю в счетчик с идентификатором 97240127 для пользователя с ClientID 1729447244995188900 JavaScript-событие measurement-protocol-event с ценностью 1000. Предварительно необходимо создать саму цель в интерфейсе Яндекс Метрики:

Поскольку я планирую дополнить существующий визит этими данными, а не создавать новый, мой окончательный запрос для отправки будет выглядеть так:

Не забудьте в запросе в параметре ms добавить токен, полученный на предыдущем шаге.

Так как Measurement Protocol для Яндекс Метрики на mc.yandex.ru/collect поддерживает методы POST и GET, вы можете вставить итоговый запрос в адресную строку браузера и нажать Enter. Запрос будет отправлен.

Примечание: когда ваш программист будет автоматизировать процесс передачи данных через Measurement Protocol, вероятно, он будет использовать метод POST.

Вы также можете открыть консоль разработчика, перейти на вкладку Network / Сеть и проверить, корректно ли отправились данные и с каким статусом ответа:

И посмотреть на сам запрос и его параметры на вкладке Payload (Полезная нагрузка):

Если вы все сделали правильно, то в течение 20 минут данные будут записаны в ваш счетчик Яндекс Метрики.

Виктор Кончишин, эксперт по работе с аналитическими инструментами, автор алгоритма самостоятельной установки и настройки CAPI с помощью Google Tag Manager, на контентной платформе lib.osipenkov.ru опубликовал любопытный материал, в котором он показывает, как передавать данные в Яндекс Метрику (цели) через Measurement Protocol методом POST с помощью серверного контейнера Google Tag Manager.