Загрузка данных

Передача данных осуществляется на URL https://mc.yandex.ru/collect POST или GET-запросами. Каждый параметр в запросе представляет собой пару ключ=значение. Все значения параметров должны быть URL-кодированы и закодированы в формате UTF-8 (см. пример передачи просмотра).

Несколько взаимодействий можно отправить одним запросом — см. Пакетная передача данных.

Обязательные параметры

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

tid — номер счетчика;
cid — идентификатор клиента ClientID;
t — тип взаимодействия;
ms — секретный токен Measurement Protocol.

Остальные параметры зависят от того, что вы передаете:

Что передаете	Какие параметры добавить
Просмотр страницы	`t=pageview` и URL страницы `dl`. Рекомендуется также передавать заголовок страницы `dt` и реферер `dr`
Достижение JavaScript-цели	`t=event` и идентификатор цели `ea`. Для цели с ценностью — также `ev` и `cu`
Ecommerce-событие	`t=event`, действие `pa` и параметры товаров `pr<productIndex>…`. Для покупки (`pa=purchase`) обязателен идентификатор транзакции `ti`, рекомендуется доход `tr`
Параметры визита	`params` — вместе с любым просмотром или событием

Поддерживаемые параметры

Параметр	Описание	Комментарий
`tid`	Номер счетчика	Обязательный. Для счетчика должна быть включена опция Measurement Protocol, иначе запрос будет отклонен
`cid`	Идентификатор клиента `ClientID`. Целое неотрицательное число	Обязательный. Значение в другом формате будет отклонено
`t`	Тип взаимодействия. Возможные значения: `pageview` — просмотр страницы `event` — JavaScript-событие, ecommerce-события	Обязательный
`dr`	Реферер	Необязательный. Передается с просмотром (`t=pageview`); влияет на определение источника трафика. При прямом заходе не передается
`dl`	URL страницы	Передавайте при каждом просмотре (`t=pageview`) — это адрес просматриваемой страницы. Также обязателен для любого события `event`, если включена опция «Принимать данные только с указанных адресов»
`dt`	Заголовок страницы	Необязательный. Передается с просмотром (`t=pageview`)
`ea`	Идентификатор JavaScript-цели	Передается для достижения цели (`t=event`). Значение должно совпадать с идентификатором цели типа «JavaScript-событие» в счетчике. Для ecommerce-событий вместо `ea` используется `pa`
`params`	Параметры визита	Отправляются вместе с событиями `pageview` или `event`. Значение должно быть валидным JSON, иначе запрос будет отклонен. На передачу действуют ограничения
`ti`	Ecom транзакция	Обязательный при `pa=purchase` — без него запрос будет отклонен
`tr`	Ecom доход транзакции	Необязательный. Рекомендуется передавать при `pa=purchase` — это сумма покупки
`tcc`	Ecom купон транзакции	Необязательный. Передается при `pa=purchase`
`et`	Время события — Unix-время в секундах (не в миллисекундах)	Если не передан, используется время получения запроса. Допускается не более 12 часов назад от текущего времени, иначе запрос будет отклонен
`pa`	Ecom действие с товаром (расширенный ecom). Возможные значения: `detail` — просмотр информации `add` — добавление в корзину `remove` — удаление из корзины `purchase` — покупка	Передается для ecommerce-событий (`t=event`). Вместе с `pa` передайте параметры товаров (см. раздел «Параметры товаров»)
`pr<productIndex>…`	Параметры товаров	См. раздел «Параметры товаров»
`sr`	Размер окна	Необязательный. Формат: `ширина x высота x глубина цвета`, например `1440x900x30`
`cu`	Валюта	Поддерживается для целей с ценностью и для ecom-событий
`ev`	Ценность цели	Поддерживается при передаче целей
`ms`	Секретный токен	Обязательный. Генерируется при включении опции Measurement Protocol. Запрос без токена или с токеном от другого счетчика будет отклонен

Параметры товаров

Состав товаров в ecommerce-событии передается параметрами вида pr<productIndex><поле>, где <productIndex> — порядковый номер товара в запросе, начиная с 1. Например, pr1id — код первого товара, pr2id — код второго. Так в одном запросе можно передать несколько товаров.

Для каждого товара укажите хотя бы код pr<productIndex>id или название pr<productIndex>nm. Остальные поля необязательные:

Параметр	Описание
`pr<productIndex>id`	Код товара (например, SKU). Укажите `id` и/или `nm`
`pr<productIndex>nm`	Название товара. Укажите `id` и/или `nm`
`pr<productIndex>br`	Бренд товара
`pr<productIndex>ca`	Категория товара
`pr<productIndex>va`	Разновидность товара
`pr<productIndex>pr`	Цена товара
`pr<productIndex>qt`	Количество единиц товара
`pr<productIndex>ps`	Позиция товара в списке
`pr<productIndex>cc`	Код купона товара

Например, часть запроса

pa=add&pr1id=456&pr1nm=iphone&pr1br=apple&pr1pr=50000

означает: добавление в корзину (pa=add) одного товара с кодом 456 (pr1id), названием iphone (pr1nm), брендом apple (pr1br) и ценой 50000 (pr1pr).

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

Примечание

Прежде чем выполнять примеры, подставьте номер своего счетчика (tid), свой токен (ms) и актуальное время события (et) — сервер отклонит запрос, если значение et отстает от момента отправки больше чем на 12 часов. Параметр et можно не передавать, тогда будет использовано время отправки данных.

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

https://mc.yandex.ru/collect/?tid=5564333&cid=1710232430899999999&t=pageview&dr=https%3A%2F%2Fyandex.ru&dl=https%3A%2F%2Ftest.com&dt=Test&et=1632467908&ms=01c0a669-d38c-4385-9d22-47cf894ed687

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

https://mc.yandex.ru/collect/?tid=5564333&cid=1710232430899999999&t=event&ea=order-success&et=1632467909&dl=https%3A%2F%2Ftest.com&ms=01c0a669-d38c-4385-9d22-47cf894ed687

Достижение js-цели с параметрами визита

Передаваемые параметры визита:

{"level1_1":{"level2_1":{"level3_1":"example1","level3_2":"example2"}}}

Запрос (значение params URL-кодировано):

https://mc.yandex.ru/collect/?tid=5564333&cid=1710232430899999999&t=event&ea=order-success&params=%7B%22level1_1%22%3A%7B%22level2_1%22%3A%7B%22level3_1%22%3A%22example1%22%2C%22level3_2%22%3A%22example2%22%7D%7D%7D&et=1632467909&dl=https%3A%2F%2Ftest.com&ms=01c0a669-d38c-4385-9d22-47cf894ed687

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

https://mc.yandex.ru/collect/?tid=5564333&cid=1710232430899999999&t=event&et=1632467910&pa=detail&pr1id=456&pr1nm=iphone&pr1br=apple&pr1pr=50000&ms=01c0a669-d38c-4385-9d22-47cf894ed687

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

https://mc.yandex.ru/collect/?tid=5564333&cid=1710232430899999999&t=event&et=1632467911&pa=add&pr1id=456&pr1nm=iphone&pr1br=apple&pr1pr=50000&ms=01c0a669-d38c-4385-9d22-47cf894ed687

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

https://mc.yandex.ru/collect/?tid=5564333&cid=1710232430899999999&t=event&et=1632467912&pa=purchase&pr1id=456&pr1nm=iphone&pr1br=apple&pr1pr=50000&ti=4555&tr=50000&ms=01c0a669-d38c-4385-9d22-47cf894ed687

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

Товары нумеруются параметром <productIndex>: первый товар — pr1…, второй — pr2….

https://mc.yandex.ru/collect/?tid=5564333&cid=1710232430899999999&t=event&et=1632467913&pa=purchase&pr1id=456&pr1nm=iphone&pr1br=apple&pr1pr=50000&pr2id=459&pr2nm=airpods&pr2br=apple&pr2pr=20000&ti=4555&tr=70000&ms=01c0a669-d38c-4385-9d22-47cf894ed687

Пакетная передача данных

Чтобы не отправлять каждое взаимодействие отдельным запросом, объедините несколько хитов в один POST-запрос:

параметры, общие для всех хитов (как минимум tid и ms), укажите один раз в строке запроса (query string);
в теле запроса передайте каждый хит отдельной строкой — в том же формате ключ=значение&ключ=значение, что и обычный запрос.

Параметры из строки запроса автоматически добавляются к каждой строке тела, и каждая строка проверяется по обычным правилам — как самостоятельный запрос (см. раздел «Обязательные параметры»).

Пример

Один запрос передает просмотр, достижение цели и покупку для одного посетителя. Содержимое файла hits.txt:

cid=1710232430899999999&t=pageview&dl=https%3A%2F%2Ftest.com&dt=Main
cid=1710232430899999999&t=event&ea=order-success
cid=1710232430899999999&t=event&pa=purchase&pr1id=456&pr1nm=iphone&pr1pr=50000&ti=4555&tr=50000

Отправка:

curl -X POST 'https://mc.yandex.ru/collect/?tid=5564333&ms=01c0a669-d38c-4385-9d22-47cf894ed687' \
     --data-binary @hits.txt

Если все строки приняты, сервер вернет HTTP 200 с телом .

Правила формирования пакета

Одна строка — один хит. Разделитель строк — \n или \r\n.
Без пустых строк и без перевода строки в конце тела. Пустая строка считается отдельным хитом без параметров, не проходит проверку — и весь запрос будет отклонен (Parameter 't' is required).
Значение из строки запроса имеет приоритет. Если параметр указан и в строке запроса, и в строке тела, будет использовано значение из строки запроса. Поэтому выносите в строку запроса только то, что действительно общее для всех хитов — например, tid и ms. Параметры, которые различаются (cid, t, et и т. д.), передавайте в строках тела.
В одном пакете можно смешивать любые типы хитов — просмотры, цели, ecommerce-события — и разных посетителей (разные cid).
Размер тела — не больше 1 МБ. Данные сверх лимита отбрасываются без сообщения об ошибке, поэтому превышать его нельзя — часть хитов будет потеряна, даже если сервер вернет 200 OK. Рекомендуем формировать пакеты с запасом (например, до 500 КБ) и разбивать большие объемы на несколько запросов. Ограничения на количество строк нет — в 1 МБ помещаются десятки тысяч хитов.
Тело можно сжимать gzip — передайте заголовок Content-Encoding: gzip. Это экономит трафик, но не увеличивает лимит: 1 МБ считается по несжатым данным.
Ответ сервера — один на весь пакет. 200 OK — приняты все строки; 400 с текстом первой ошибки — хотя бы одна строка не прошла проверку. Информации о том, какая именно строка ошибочна, в ответе нет, поэтому проверяйте данные до отправки (в том числе ограничение et — не старше 12 часов на момент отправки — для каждой строки).

Ответ сервера

Если данные приняты, сервер возвращает HTTP 200 с телом .

Если запрос отклонен, сервер возвращает HTTP 400, а причина указывается в теле ответа в виде HTML-комментария. Возможные ошибки:

Текст ошибки	Причина и способ устранения
`Parameter 'tid' is required`	Не передан номер счетчика
`Measurement protocol is not enabled`	Для счетчика с этим номером не включена опция Measurement Protocol. Проверьте значение `tid` и настройки опции
`Request must contain cid`	Не передан идентификатор клиента `cid`
`Invalid format of 'cid' parameter`	`cid` должен быть целым неотрицательным числом
`Parameter 't' is required`	Не передан тип взаимодействия `t`
`Parameter 'ms' is required`	Не передан секретный токен `ms`
`Invalid measurement protocol token`	Токен `ms` не подходит к счетчику `tid`. Проверьте, что токен скопирован полностью и не был удален
`Parameter 'et' is out of acceptable time limit`	Время события `et` старше 12 часов. Убедитесь также, что передаете время в секундах
`Parameter 'ti' is required`	Передано событие покупки (`pa=purchase`) без идентификатора транзакции `ti`
`Parameter 'params' isn't valid JSON`	Значение `params` не является валидным JSON

Важно

Ответ 200 OK означает, что запрос принят, а не то, что все параметры заполнены корректно. Например, событие t=event без ea и pa будет принято, но не попадет ни в цели, ни в ecommerce-отчеты. Проверяйте результат загрузки в отчетах Метрики.

Особенности

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

Была ли статья полезна?

Управление опцией и токенами

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