В этом документе рассматривается отправка данных в 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. Остальные параметры будут обработаны, как обычно.
Measurement Protocol поддерживает следующие типы данных:
Обратите внимание, что для отдельных полей данных могут действовать собственные ограничения. Список всех полей данных и поддерживаемых значений можно просмотреть в Справке по полям.
Текст
Представляет строки. Тестовые поля проходят дополнительную обработку: начальные и конечные пробелы удаляются, а двойные, тройные и более символы разметки (включая пробелы, табуляцию, разрывы строки и т. д.) преобразуются в одинарные. Это преобразование выполняется над необработанным текстом до каких-либо сокращений. Например,
Hello World
примет следующий вид:
Hello World
Currency
Представляет общую сумму в валюте. Десятичная часть отделяется от целой точкой. После десятичной точки может идти до 6 знаков. Пример допустимого значения в поле валюты:
1000.000001
После отправки в Google Analytics будет удален весь текст до первой цифры, дефиса (-
) или десятичной точки (.
).
Таким образом,
$-55.00
примет следующий вид:
-55.00
Boolean
Позволяет установить истинность значения. Возможные варианты:
1
– истина;0
– ложь.
Integer
Представляет целое число. Сохраняется как значение int64 со знаком.
Number
Представляет целое число или число с плавающей запятой.