Справка по Measurement Protocol

В этом документе рассматривается отправка данных в Google Analytics с помощью протокола передачи статистических данных (Measurement Protocol).

Обзор

Процесс отправки статистики в Google Analytics с помощью Measurement Protocol включает два компонента:

• Транспортировка: куда и как вы посылаете данные.
• Полезная нагрузка: сама отправляемая вами информация.

Далее рассказывается о форматировании обоих этих компонентов.

Транспортировка

URL конечной точки

При использовании Measurement Protocol HTTP-запросы отправляются в следующую конечную точку:

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

Для передачи информации необходимо использовать протокол HTTPS.

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

POST

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

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

Пояснения:

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

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

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

GET

В средах, где 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, а извлекаться из кеша. Для очистки кеша в Measurement Protocol есть специальный параметр (z), принимающий в качестве значения случайно выбранное число. Это обеспечивает уникальность всех запросов и предотвращает извлечение из кеша последующих запросов.

Мы рекомендуем добавлять параметр очистки кеша последним:

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

Коды ответа

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

Если вы не получили код статуса 2xx, не повторяйте запрос, не исправив сначала ошибки в HTTP-запросе.

Строка передаваемых данных

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

key1=val1&key2=val2

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

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

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

Следующие параметры должны передаваться всегда:

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

Значения параметров Client ID (Идентификатор клиента) и Hit Type (Тип обращения) напрямую сопоставляются с моделью данных Google Analytics. Например, если вы хотите отслеживать пользователя 5555, посетившего страницы /pageA, /pageB и /pageC, то нужно будет отправить следующие три строки данных:

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.

Кодирование значений

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

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

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

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

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

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

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

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

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

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

Measurement Protocol поддерживает следующие типы данных:

• Текст
• Currency
• Boolean
• Integer
• Number

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

Текст

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

   Hello      World

примет следующий вид:

Hello World

Currency

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

1000.000001

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

$-55.00

примет следующий вид:

-55.00

Boolean

Позволяет установить истинность значения. Возможные варианты:

• 1 – истина;
• 0 – ложь.

Integer

Представляет целое число. Сохраняется как значение int64 со знаком.

Number

Представляет целое число или число с плавающей запятой.