--- metadata: - name: generator content: Diplodoc Platform v5.70.0 alternate: - https://yandex.com/dev/metrika/en/data-import/measurement-upload.md - https://yandex.com/dev/metrika/ru/data-import/measurement-upload.md - href: https://yandex.com/dev/metrika/ru/data-import/measurement-upload.md type: text/markdown title: Markdown version - href: https://yandex.com/dev/metrika/ru/llms.txt?revision=r22093398 rel: describedby --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/metrika/ru/llms.txt?revision=r22093398 # Загрузка данных Передача данных осуществляется на URL `https://mc.yandex.ru/collect` POST или GET-запросами. Каждый параметр в запросе представляет собой пару `ключ=значение`. Все значения параметров должны быть URL-кодированы и закодированы в формате UTF-8 (см. [пример передачи просмотра](#examples)). Несколько взаимодействий можно отправить одним запросом — см. [Пакетная передача данных](#batch). ## Обязательные параметры {#required} В каждом запросе, независимо от типа взаимодействия, обязательно передаются четыре параметра. Без любого из них сервер отклонит запрос с ошибкой: - `tid` — номер счетчика; - `cid` — идентификатор клиента `ClientID`; - `t` — тип взаимодействия; - `ms` — секретный токен Measurement Protocol. Остальные параметры зависят от того, что вы передаете: |Что передаете|Какие параметры добавить| |:---|:---| |Просмотр страницы|`t=pageview` и URL страницы `dl`. Рекомендуется также передавать заголовок страницы `dt` и реферер `dr`| |Достижение JavaScript-цели|`t=event` и идентификатор цели `ea`. Для цели с ценностью — также `ev` и `cu`| |Ecommerce-событие|`t=event`, действие `pa` и параметры товаров `pr…`. Для покупки (`pa=purchase`) обязателен идентификатор транзакции `ti`, рекомендуется доход `tr`| |Параметры визита|`params` — вместе с любым просмотром или событием| ## Поддерживаемые параметры {#parameters} #| || **Параметр** | **Описание** | **Комментарий** || || `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, иначе запрос будет отклонен. На передачу действуют [ограничения](https://yandex.ru/support/metrica/general/limits.html#limits__param) || || `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` передайте параметры товаров (см. раздел [«Параметры товаров»](#products)) || || `pr…` | Параметры товаров | См. раздел [«Параметры товаров»](#products) || || `sr` | Размер окна | Необязательный. Формат: `ширина x высота x глубина цвета`, например `1440x900x30` || || `cu` | Валюта | Поддерживается для целей с ценностью и для ecom-событий || || `ev` | Ценность цели | Поддерживается при передаче целей || || `ms` | Секретный токен | **Обязательный.** Генерируется при включении опции Measurement Protocol. Запрос без токена или с токеном от другого счетчика будет отклонен || |# ## Параметры товаров {#products} Состав товаров в ecommerce-событии передается параметрами вида `pr<поле>`, где `` — порядковый номер товара в запросе, начиная с 1. Например, `pr1id` — код первого товара, `pr2id` — код второго. Так в одном запросе можно передать несколько товаров. Для каждого товара укажите хотя бы код `prid` или название `prnm`. Остальные поля необязательные: |Параметр|Описание| |:---|:---| |`prid`|Код товара (например, SKU). Укажите `id` и/или `nm`| |`prnm`|Название товара. Укажите `id` и/или `nm`| |`prbr`|Бренд товара| |`prca`|Категория товара| |`prva`|Разновидность товара| |`prpr`|Цена товара| |`prqt`|Количество единиц товара| |`prps`|Позиция товара в списке| |`prcc`|Код купона товара| Например, часть запроса ``` pa=add&pr1id=456&pr1nm=iphone&pr1br=apple&pr1pr=50000 ``` означает: добавление в корзину (`pa=add`) одного товара с кодом `456` (`pr1id`), названием `iphone` (`pr1nm`), брендом `apple` (`pr1br`) и ценой `50000` (`pr1pr`). ## Примеры передачи данных {#examples} {% note info %} Прежде чем выполнять примеры, подставьте номер своего счетчика (`tid`), свой токен (`ms`) и актуальное время события (`et`) — сервер отклонит запрос, если значение `et` отстает от момента отправки больше чем на 12 часов. Параметр `et` можно не передавать, тогда будет использовано время отправки данных. {% endnote %} #### Отправка просмотра ```http translate=no 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 ```http translate=no 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-цели с параметрами визита Передаваемые параметры визита: ```json {"level1_1":{"level2_1":{"level3_1":"example1","level3_2":"example2"}}} ``` Запрос (значение `params` URL-кодировано): ```http translate=no https://mc.yandex.ru/collect/?tid=5564333&cid=1710232430899999999&t=event&ea=order-success¶ms=%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 ```http translate=no 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 ``` #### Добавление товара в корзину ```http translate=no 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 ``` #### Покупка товара ```http translate=no 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 ``` #### Покупка нескольких товаров Товары нумеруются параметром ``: первый товар — `pr1…`, второй — `pr2…`. ```http translate=no 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 ``` ## Пакетная передача данных {#batch} Чтобы не отправлять каждое взаимодействие отдельным запросом, объедините несколько хитов в один POST-запрос: - параметры, **общие для всех хитов** (как минимум `tid` и `ms`), укажите один раз в строке запроса (query string); - в **теле запроса** передайте каждый хит отдельной строкой — в том же формате `ключ=значение&ключ=значение`, что и обычный запрос. Параметры из строки запроса автоматически добавляются к каждой строке тела, и каждая строка проверяется по обычным правилам — как самостоятельный запрос (см. раздел [«Обязательные параметры»](#required)). ### Пример {#batch-example} Один запрос передает просмотр, достижение цели и покупку для одного посетителя. Содержимое файла `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 ``` Отправка: ```bash curl -X POST 'https://mc.yandex.ru/collect/?tid=5564333&ms=01c0a669-d38c-4385-9d22-47cf894ed687' \ --data-binary @hits.txt ``` Если все строки приняты, сервер вернет `HTTP 200` с телом ``. ### Правила формирования пакета {#batch-rules} 1. **Одна строка — один хит.** Разделитель строк — `\n` или `\r\n`. 1. **Без пустых строк и без перевода строки в конце тела.** Пустая строка считается отдельным хитом без параметров, не проходит проверку — и весь запрос будет отклонен (`Parameter 't' is required`). 1. **Значение из строки запроса имеет приоритет.** Если параметр указан и в строке запроса, и в строке тела, будет использовано значение из строки запроса. Поэтому выносите в строку запроса только то, что действительно общее для всех хитов — например, `tid` и `ms`. Параметры, которые различаются (`cid`, `t`, `et` и т. д.), передавайте в строках тела. 1. **В одном пакете можно смешивать любые типы хитов** — просмотры, цели, ecommerce-события — и разных посетителей (разные `cid`). 1. **Размер тела — не больше 1 МБ.** Данные сверх лимита отбрасываются без сообщения об ошибке, поэтому превышать его нельзя — часть хитов будет потеряна, даже если сервер вернет `200 OK`. Рекомендуем формировать пакеты с запасом (например, до 500 КБ) и разбивать большие объемы на несколько запросов. Ограничения на количество строк нет — в 1 МБ помещаются десятки тысяч хитов. 1. **Тело можно сжимать gzip** — передайте заголовок `Content-Encoding: gzip`. Это экономит трафик, но не увеличивает лимит: 1 МБ считается по несжатым данным. 1. **Ответ сервера — один на весь пакет.** `200 OK` — приняты все строки; `400` с текстом первой ошибки — хотя бы одна строка не прошла проверку. Информации о том, какая именно строка ошибочна, в ответе нет, поэтому проверяйте данные до отправки (в том числе ограничение `et` — не старше 12 часов на момент отправки — для каждой строки). ## Ответ сервера {#response} Если данные приняты, сервер возвращает `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| {% note warning %} Ответ `200 OK` означает, что запрос принят, а не то, что все параметры заполнены корректно. Например, событие `t=event` без `ea` и `pa` будет принято, но не попадет ни в цели, ни в ecommerce-отчеты. Проверяйте результат загрузки в отчетах Метрики. {% endnote %} ## Особенности {#nuance} - Через Measurement Protocol можно создать визит, либо дополнить существующий визит. - Для создания визита нужно обязательно указать `ClientID` пользователя. - Для формирования визита нужно передать как минимум один просмотр страницы (`t=pageview`) в начале визита. - Визиты формируются по тем же правилам и ограничениям, что и обычные визиты. - Данные можно отправить максимум на 12 часов назад от текущего времени. Если не отправлять параметр `et` — будет указано время отправки данных. - Обновить визит можно только в рамках тайм-аута визита, указанного в настройках счетчика, используя параметр `et` или отправляя данные без этого параметра в пределах тайм-аута визита. Если выйти за тайм-аут — начнется новый визит (после отправки `pageview`).