Справочное руководство по Measurement Protocol

В этом документе описывается, как отправлять данные в Google Analytics с помощью протокола измерений.

Обзор

Отправка данных в Google Analytics с использованием протокола измерений состоит из двух частей:

• Транспорт – куда и как вы отправляете данные
• Полезная нагрузка — данные, которые вы отправляете

В этом документе описывается, как отформатировать оба.

Транспорт

Конечная точка URL-адреса

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

https://www.google-analytics.com/collect

Все данные должны отправляться безопасно по протоколу HTTPS.

Вы можете отправлять данные с помощью запросов POST или GET.

Использование POST

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

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

Где:

• user_agent_string — это форматированная строка пользовательского агента , которая используется для вычисления следующих параметров: браузер, платформа и возможности мобильных устройств.

  Если это значение не установлено, приведенные выше данные не будут рассчитываться.

• payload_data – BODY почтового запроса. Тело должно включать ровно 1 полезную нагрузку, закодированную в URI, и его длина не должна превышать 8192 байта.
• IP-адрес — неявно отправляется в HTTP-запросе и используется для вычисления всех географических/сетевых параметров в Google Analytics.

ПОЛУЧАТЬ

В средах, где вы не можете отправлять данные POST, вы также можете отправлять HTTP-запросы GET в ту же конечную точку:

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

Где полезные данные отправляются как параметры запроса с экранированием URI. Длина всего закодированного URL-адреса не должна превышать 8000 байт.

Очистка кэша

В некоторых средах, например в браузерах, запросы HTTP GET могут кэшироваться. Когда запрос кэшируется, последующие запросы могут быть получены из кэша, а не отправлены в Google Analytics. Чтобы обойти кеш, протокол измерений предоставляет специальный параметр ( z ), которому можно задать случайное число. Это гарантирует, что все запросы протокола измерений уникальны и последующие запросы не извлекаются из кэша.

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

https://www.google-analytics.com/collect?payload_data&z=123456

Коды ответа

Протокол измерения вернет код состояния 2xx , если HTTP-запрос был получен. Протокол измерения не возвращает код ошибки, если полезные данные были неверными, или если данные в полезных данных были неверными или не были обработаны Google Analytics.

Если вы не получили код состояния 2xx , вам НЕ следует повторять запрос. Вместо этого вам следует остановить и исправить любые ошибки в вашем HTTP-запросе.

Данные полезной нагрузки

Все данные, собранные Google Analytics с использованием протокола измерений, отправляются в виде полезной нагрузки. Полезные данные напоминают строку запроса URL-адреса, где каждый параметр имеет ключ и значение, разделены символом = , а каждая пара разделена символом & . Например:

key1=val1&key2=val2

Каждая полезная нагрузка имеет правила, определяющие: обязательные значения, кодировку URI, параметры, которые можно отправлять вместе, и длину параметра. Также каждый параметр имеет определенный тип, требующий определенного формата. В следующих разделах рассматриваются эти правила.

Прочтите Справочник параметров , чтобы получить полный список всех параметров, которые вы можете отправить с помощью протокола измерений.

Обязательные значения для всех обращений

В каждой полезной нагрузке должны присутствовать следующие параметры:

Имя	Параметр	Пример	Описание
Версия протокола	v	v= 1	Версия протокола. Значение должно быть 1 .
Идентификатор отслеживания	tid	tid= UA-123456-1	Идентификатор, который определяет, в какой ресурс Google Analytics отправлять данные.
ID клиента	cid	cid= xxxxx	Идентификатор, уникальный для конкретного пользователя.
Тип попадания	t	t= pageview	Тип взаимодействия, собранный для конкретного пользователя.

Данные Client ID и Hit Type — это значения, которые напрямую соответствуют модели данных Google Analytics. Если вы хотите отслеживать пользователя 5555 который зашел на /pageA , /pageB и /pageC , вы должны отправить следующие 3 полезных данных:

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

Обратите внимание, что / был закодирован как %2F .

Значения кодировки URL-адреса

Все значения, отправляемые в Google Analytics, должны иметь кодировку UTF-8 и URL . Чтобы отправить ключ dp со значением /my page € , вам сначала нужно убедиться, что он закодирован в UTF-8, а затем в кодировке url, в результате чего получится окончательная строка:

dp=%2Fmy%20page%20%E2%82%AC

Если какой-либо из символов закодирован неправильно, он будет заменен символом замены Юникода xFFFD .

Обязательные значения для определенных типов обращений

Некоторые параметры могут отправляться только с определенными типами обращений. Например, тип обращения pageview требует, чтобы также был установлен параметр «Путь к странице» ( dp ). Справочник параметров описывает, какие параметры необходимы для каких типов попаданий.

Максимальная длина

Некоторые текстовые значения в протоколе измерений имеют определенную максимальную длину в байтах. Например, поле реферера документа dr имеет максимальную длину 2048 байт. Если какое-либо из значений превышает максимальную длину, оно будет автоматически усечено. Если многобайтовый символ превышает максимальную длину, весь символ будет обрезан.

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

Каждое поле данных в протоколе измерений относится к определенному типу, каждое из которых имеет свои собственные правила проверки. Если какое-либо из значений параметра не соответствует правилам проверки, этот конкретный параметр будет игнорироваться и не обрабатываться Google Analytics. Все остальные параметры будут обработаны как обычно.

Примечание . Если обязательный параметр имеет неверный формат, вся полезная нагрузка не будет обработана. Например, отправка bogus значения для требуемого параметра типа попадания приведет к тому, что вся полезная нагрузка не будет обработана.

Протокол измерений поддерживает следующие типы данных:

• Текст
• Валюта
• логическое значение
• Целое число
• Число

Обратите внимание, что отдельные поля данных могут иметь свои ограничения. Полный список всех полей данных и допустимых типов см. в Справочнике по полям .

Текст

Используется для представления строк. Дополнительная обработка выполняется в текстовых полях. Все ведущие и конечные пробелы удаляются. Внутренние прогоны двух или более пробельных символов (включая пробел, табуляцию, новую строку и т. д.) сводятся к одному символу пробела. Это преобразование применяется к необработанному тексту до того, как произойдет какое-либо усечение. Например:

   Hello      World

станет:

Hello World

Валюта

Используется для представления общей стоимости валюты. Десятичная точка используется в качестве разделителя между целой и дробной частью валюты. Точность до 6 знаков после запятой. Для поля валюты допустимо следующее:

1000.000001

После отправки значения в Google Analytics весь текст удаляется до первой цифры, символа - или . (десятичный) символ. Так:

$-55.00

станет:

-55.00

логическое значение

Используется для определения того, является ли значение истинным или ложным. Допустимые значения:

• 1 – Верно
• 0 – Ложь

Целое число

Используется для представления целого числа. Значение сохраняется как подписанное int64.

Число

Используется для представления целого числа или числа с плавающей запятой.