Параметры запроса Measurement Protocol v2 для Google Analytics 4

В Google Analytics 4 посредством специальных запросов вы можете передавать дополнительную информацию о ваших пользователях даже в том случае, если они были совершены за пределами вашего сайта или мобильного приложения, с любого устройства, подключенного к интернету. Эта технология называется Measurement Protocol (MP). О том, что входит в такой запрос и из каких параметров GA4 он состоит, подробно разберем в этом материале.

Обновление: я выпустил электронное руководство по Google Analytics 4. Бесплатно скачать его можно в формате .PDF по ссылке.

Самые распространенные способы использования данной технологии:

• отправлять данные об офлайн-конверсиях в Google Analytics;
• связывать офлайн и онлайн-конверсии между собой;
• отслеживать клиентские и серверные взаимодействия.

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

Принцип работы Measurement Protocol для Google Analytics 4 я исчерпывающе описал в этой статье. Если вы желаете познакомиться с работой Measurement Protocol для Universal Analytics (GA3), прочитайте эту публикацию. В этой статье я хотел бы остановиться не на технологии MP, ее преимуществах/недостатках, добавлении секретного ключа API, создании запроса, а на самих параметрах, которые передаются в запросе.

За основу были взяты два ключевых материала по этой теме:

1. официальную справку Google по событиям и параметрам Measurement Protocol
2. шпаргалку от Дэвида Вальехо (David Vallejo), автора блога thyngster.com

Начнем поэтапное изучение построения запросов Measurement Protocol.

Из чего состоит запрос?

Если у вас на сайте просто установлен счетчик Google Analytics 4, то вы уже используете Measurement Protocol. Каждый раз, когда на вашем сайте запускается событие page_view (просмотр страницы) или любое другое, http-запрос отправляется на сервера Google Analytics.

Чтобы увидеть http-запрос, который отправляет данные в Google Analytics 4, выполните следующие шаги:

• перейдите на сайт, где установлен GA4;
• в браузере откройте панель разработчика - вкладка Network (клавиша F12 для Google Chrome). Либо используйте вызов контекстного меню правой кнопкой мыши и команду Просмотреть код

• установите две галочки рядом с Preserve log и Disable cache:

• обновите страницу;

В таблице начнут появлятся строчки с различными запросами и временем их выполнения. Игнорируем это. В поле Filter введите идентификатор вашего потока данных Google Analytics 4. Он начинается на G-

Все сетевые запросы, которые начинаются с collect?v, являются запросами протокола измерений. У вас их может быть 1, 2 или больше. Все они передают информацию в Google Analytics через Measurement Protocol. Кликните по любому запросу из списка. Вы должны увидеть полную информацию о запросе:

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

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

• строки отправки, транспортировка (transport);
• строки набора данных с параметрами (payload data). В официальной документации Google ее называют полезной нагрузкой.

Cтрока отправки, транспортировка (transport)

Указывает куда и как отправлять данные. Пример:

Строка отправки состоит из нескольких частей:

• метод POST - определяет, как будут отправляться данные на сервер Google Analytics (/mp/collect);
• www.google-analytics.com - расположение сервера (HOST), куда будут отправляться данные;
• адрес конечной точки - URL-адрес, на который вам необходимо отправить итоговый запрос или несколько обращений в запросе (https://www.google-analytics.com/mp/collect).

URL-адрес конечной точки может содержать /collect (одно обращение), /batch (несколько обращений, событий в одном запросе) или /debug (проверка запроса).

Строка набора данных, полезная нагрузка (payload data)

Данные, которые вы отправляете в Google Analytics 4 с помощью Measurement Protocol, состоят из двух компонентов:

1. Параметры запроса

К параметрам запроса относятся:

• api_secret - секретный ключ API (API Secret);
• measurement_id - идентификатор потока данных (для веб-потоков);
• firebase_app_id - идентификатор приложения в Firebase.

Подробнее о том, как создать новый секретный ключ API и где найти идентификатора потока данных для веб-сайта, читайте в руководстве по Measurement Protocol.

2. Тело запроса POST в формате JSON

Содержит набор параметров, передаваемых в запросе. Пример:

Она очень напоминает url-адрес, в ссылке которого после символа ? передаются utm_метки. Только вместо привычных пяти переменных (utm_source, utm_medium, utm_campaign, utm_campaign и utm_term), разделенных между собой символом &, здесь используются другие параметры, которые точно так же отделяются друг от друга амперсандом.

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

Чтобы разобрать, из каких параметров состоит запрос, перейдите на вкладку Payload:

Вы увидите ваш запрос, разделенный на отдельные строки:

Чтобы посмотреть запрос в декодированном (понятном) виде, нажмите на view decoded:

Тогда часть значений, содержащая специальные символы (%D0%A1....), будет отображаться в удобочитаемом виде:

Каждая строка в запросе - это пара ключ=значение. Например:

То, что идет до знака равно - это ключ, после - значение. Например, ключами могут быть:

• v - версия Measurement Protocol (для Google Analytics 4 - 2, для Universal Analytics - 1);
• tid - идентификатор потока данных;
• cid - уникальный идентификатор пользователя (Client ID);
• ul - язык браузера пользователя;
• sr - разрешение экрана.

А их значения:

• v = 2
• tid = G-BMPB32GC7T
• cid = 1142061052.1623097982
• ul = ru-ru
• sr = 1536x864

Примечание: все значения должны быть кодированы в UTF-8 и URL-кодированы.

Помимо параметров запроса, для отправки данных с помощью Measurement Protocol необходимо сформировать тело запроса. Это те данные, которые вы планируете передать в Google Analytics 4. Они отправляются методом POST (в Universal Analytics можно POST и GET) в формате JSON (JSON - JavaScript Object Notation) - стандартный текстовый формат для представления структурированных данных на основе синтаксиса объекта JavaScript.

Тело запроса также состоит из набора параметров, без которых передача данных в Google Analytics просто невозможна. Для веб-потоков обязательными являются:

• client_id - уникальный идентификатор пользователя (Client ID);
• events - массив объектов, в котором передаются данные о событии(ях). В одном запросе можно передавать данные о максимум 25 событиях;
• events[].name - название передаваемого события.

Помните главный вопрос, который мы озвучили выше? Как Google Analytics понимает какому конкретно пользователю записать отправляемое через Measurement Protocol событие? Именно с помощью уникального идентификатора пользователя

Помимо обязательных параметров, в Google Analytics 4 есть еще ряд необязательных, но не менее полезных параметров, которые вы можете отправить с запросом:

• user_id - уникальный идентификатор пользователя, определенный внутри вашей системы (не путать с Client ID);
• timestamp_micros - метка времени Unix (в микросекундах) используется только для регистрации уже произошедших событий. С ее помощью можно переопределять временные метки (timestamp) других событий и user_property (свойства пользователя). События можно отправлять задним числом (до трех дней) по часовому поясу ресурса;
• user_properties - свойства пользователя;
• non_personalized_ads - настройка персонализированный рекламы. Чтобы не использовать события для персонализации рекламы задайте значение true;
• events[].params - параметры события.

Если вы на сайте используете Google Tag Manager, то включив режим отладки, вы можете увидеть что отправляется в Google Analytics 4 с тем или иным хитом. Для этого на странице Google Tag Assistant переключитесь с контейнера GTM на контейнер GA4 (1), а затем выберите хит, который отправляется в аналитику (2) и посмотрите его подробнее (3):

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

Например, для события page_view (просмотр страницы) передается целый ряд параметров:

• Protocol Version (v)
• Measurement ID (tid)
• gtm (gtm)
• Random Page ID (_p)
• Debug View (_dbg)
• System Property (_z)
• Internal Ping Type (_gaz)
• Client ID (cid)
• Language (ul)
• Screen Resolution (sr)
• Request Number (_s)
• Custom User ID (uid)
• Session ID (sid)
• Session Count (sct)
• Session Engagement (seg)
• Page Location (dl)
• Page Referrer (dr)
• Page Title (dt)
• Event Name (en)
• Event Parameter (ep.) - параметры, связанные с событием

Именно эти параметры запроса мы и будем разбирать ниже. Для этого я предлагаю использовать шпаргалку Google Analytics 4 Measurement Protocol.

Дэвид Вальехо расшифровал самые часто используемые параметры, а также для наглядности разделил их по категориям. При желании вы можете воспользоваться поиском для ускорения нахождения нужного параметра:

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

Тело запроса

Примечание: примеры кодов со скриншотами, используемые ниже, демонстрируются в консоли разработчика (вкладка Console).

Request Parameters (Параметры запроса)

• &v -  Protocol Version (версия протокола) // Пример: 2
• &tid - Measurement ID, Stream ID (идентификатор потока даных) // Пример: G-MH81VK4E9B
• &gtm - GTM Hash Info (если текущий хит был сгенерирован из Google Tag Manager, запрос будет содержать хэш текущей конфигурации GTM/GTAG) // Пример: 2oe6m0
• &_p - Random Page ID (случайный хэш, сгенерированный при загрузке страницы) // Пример: 549202642

Значение Random Page ID можно извлечь из глобальной переменной gaGlobal с помощью команды window.gaGlobal.hid:

Либо же использовать формулу для генерации случайного числа: Math.floor(Math.random() * (2147483647 - 0 + 1) + 0)

• &sr - Screen Resolution (разрешение экрана браузера в формате ширина x высота) // Пример: 1536x864

Значение Screen Resolution можно извлечь с помощью команды (window.screen ? window.screen.width : 0) + "x" + (window.screen ? window.screen.height : 0):

• &ul - User Language (активная локаль браузера, язык браузера пользователя) // Пример: ru-ru

Значение User Language можно извлечь с помощью команды navigator.language.toLowerCase():

• &dh - Document Hostname (текущее имя хоста документа) // Пример: osipenkov.ru

Значение Document Hostname можно извлечь с помощью команды document.location.hostname:

• &cid - Client ID (уникальный идентификатор пользователя) // Пример: 50318434.1655577337

Значение Client ID можно извлечь с помощью команды ('; ' + document.cookie).split('; _ga=').pop().split(';').shift().match(/GA1\.[0-9]{1}\.(.+)/)[1]:

О том, как еще извлекать значение Client ID, читайте в этих материалах:

• Client ID в Google Analytics 4
• Передача Client ID через Google Tag Manager (+видео)
• Самый простой способ передачи Client ID в Google Analytics

Еще значение cid можно извлечь из глобальной переменной gaGlobal с помощью команды window.gaGlobal.vid:

• &_s  - Hit Counter / Request Number (счетчик хитов, обращений на текущей странице) // Пример: 2
• &richsstsse (предполагается, что этот параметр должен обогатить обращения GA4 для отправки данных в Server-Side GTM (sGTM). На текущий момент устанавливается как пустое значение) // Пример:
• &_uip - User IP Address (IP-адрес пользователя. Это должен быть действительный IP-адрес в формате IPv4 или IPv6. Он всегда будет анонимным. Последний октет удален) // Пример: 109.252.60.45

Shared (Общие параметры)

• &dl - Document Location (часть URL, содержащий путь к загруженной странице) // Пример: /google-optimize-to-ga4/

Значение Document Location можно извлечь с помощью команды document.location.pathname:

• &dt - Document Title (заголовок страницы) // Пример: Связь Google Optimize с Google Analytics 4

Значение Document Title можно извлечь с помощью команды document.title:

• &dr - Document Referrer (URI страницы, с которой был совершен переход на текущую) // Пример: https://www.google.com/

Значение Document Referrer можно извлечь с помощью команды document.referrer:

• &_z - Неизвестный параметр (значение в формате ccd.{{HASH}}, хэш на основе различных внутренних параметров. Какой-то хэш использования) // Пример: ccd.v9B
• &_eu - Event Usage (хэш, определяющий использование текущего события) // Пример: Q
• &edid - Event Debug ID? (нет данных по этому параметру запроса)
• &_dbg - Debug Mode (активен режим отладки, если передается данный параметр со значением 1) // Пример: 1
• &ir - Ignore Referrer (если у текущего запроса есть реферер, он будет проигнорирован на уровне обработки и не попадет в отчеты GA4. Настройка используется для списка нежелательных переходов, где в запросе добавляется дополнительный параметр ignore_referrer со значением true) // Пример: 1 (true)
• &tt - Traffic Type (в Measurement Protocol предыдущей версии данный параметр передавал налог с транзакции (Transaction Tax)) // Пример: 1
• &gcs - Google Consent Status (текущий статус согласия Google в формате 'G1'+'AdsStorageBoolStatus'+ 'AnalyticsStorageBoolStatus') // Пример: G101
• &gcu - Google Consent Update (будет добавлено значение 1, если согласие Google только что было обновлено (параметр wait_for_update в GTAG)) // Пример: 1
• &_glv - is Google Linker Valid  (вероятно, является одним из параметров связывания двух доменов) // Пример: 1

Campaign Attribution (Определение кампаний)

• &cm - Campaign Medium (канал кампании (как правило, передается в метке utm_medium)) // Пример: cpc
• &cs - Campaign Source (источник кампании (как правило, передается в метке utm_source) // Пример: google
• &cn - Campaign Name (название кампании (как правило, передается в метке utm_campaign) // Пример: poisk-zelevie-msk
• &cc - Campaign Content (содержание кампании (как правило, передается в метке utm_content) // Пример: image1
• &ck - Campaign Term (ключевое слово кампании (как правило, передается в метке utm_term) // Пример: google analytics 4
• &ccf - Campaign Creative Format (тип объявления кампании (передается в новой метке utm_creative_format) // Пример: video
• &cmt - Campaign Marketing Tactic (критерий таргетинга, применяемый к кампании (передается в новой метке utm_marketing_tactic) // Пример: remarketing

Event Parameters (Параметры события)

• &en - Event Name (название события, не должно превышать 40 символов) // Пример: page_view
• &_et - Engagement Time (общее время взаимодействия в миллисекундах с момента последнего события. Время взаимодействия измеряется только тогда, когда текущая страница/окно/вкладка браузера активны и видимы. Для этого GA4 использует браузерные события window.events: focus, blur, pageshow, pagehide и visibilitychange. Именно они определяют, когда таймер запускается и приостанавливается) // Пример: 1234
• &ep.* - Event Parameter (параметр события в формате string/строка) // Пример: ep.content_group: Google Analytics 4
• &epn.* - Event Parameter (параметр события в формет number/число) // Пример: epn.percent_scrolled: 75
• &_c - Conversion (событие-конверсия, 1 - если текущее событие установлено как конверсия в интерфейсе) // Пример: 1

Session / User Related (Связанные с сеансом/пользователем)

• &uid - User ID (идентификатор пользователя, определенный системой) // Пример: 232
• &_fid - Firebase ID (идентификатор пользователя Firebase) // Пример: 123456
• &sid - Session ID (идентификатор сеанса) // Пример: 1635691016

Значение Session ID можно извлечь из файла cookie с помощью команды:

, где:

• _ga_BMPB32GC7T - это ваш основной файл-cookie с идентификатором потока данных, сохраненный в браузере;

Пример выполненной команды:

Этот же идентификатор вы можете увидеть в инструменте DebugView когда тестируете события в параметре ga_session_id:

• &sct - Session Count (номер сеанса, значение увеличивается на +1 как только начинается новый сеанс) // Пример: 7

Значение Session Count можно извлечь из файла cookie с помощью команды:

, где:

• _ga_BMPB32GC7T - это ваш основной файл-cookie с идентификатором потока данных, сохраненный в браузере;

Пример выполненной команды:

Этот же идентификатор вы можете увидеть в инструменте DebugView когда тестируете события в параметре ga_session_number:

• &seg - Session Engagement (если сеанс с взаимодействием, то значение данного параметра будет равно 1) // Пример: 1
• &up.* - User Property (свойство пользователя в формате string/строка) // Пример: up.couponActivated: Yes
• &upn.* - User Property (свойство пользователя в формате number/число) // Пример: upn.couponValue: 500
• &_fv - First Visit (параметр для первого визита пользователя. Если файл cookie не установлен или еще не создан в браузере, этот параметр будет присутствовать в первом событии, а в Google Analytics 4 будет создано новое событие first_visit. Если это событие также является конверсией, значение будет 2, если нет, то 1) // Пример: 1|2
• &_ss - Session Start (начало сеанса пользователя. Если значение времени последнего сеанса файла cookie пользователя старше 1800 секунд, этот параметр будет присутствовать в текущем событии, а в Google Analytics 4 будет создано новое событие session_start. Если это событие также является конверсией, значение будет 2, если нет, то 1) // Пример: 1|2
• &_fplc - First Party Linker Cookie (по-видимому, параметр связан с обращениями на стороне сервера (Server-Side). 0 - если файл cookie FPLC отсутствует, и текущее значение, если оно исходит от междоменного компоновщика) // Пример: 0 или bVhVicbfiSXaGNxeawKaPlDQc9QXPD6bKcsn36Elden6wZNb7Q5X1iXlkTVP5iP3H3y76cgM3UIgHCaRsYfPoyLGlbiIYMPRjvnUU7KWbdWLagodzxjrlPnvaRZJkw%253D%253D
• &_nsi - New Session ID (идентификатор нового сеанса. Если текущий пользователь имеет файл cookie сеанса GA4, но не файл cookie идентификатора клиента (_ga), этот параметр будет добавлен к хиту) // Пример: 1
• &gdid - Google Developer ID (этот параметр может присутствовать, если вы используете какой-либо плагин поставщика услуг или платформу (например, используя интеграцию с магазином Shopify или плагин PrestaShop) // Пример: jdhsd87

E-Commerce (Общие данные электронной торговли)

• &cu - Currency Code (код валюты в стандарте ISO 4217) // Пример: RUB
• &ep.affiliation - Affiliation (магазин или филиал, в котором произошло событие) // Пример: Partner Shop 75
• &epn.value - Transaction Revenue (общий доход от транзакции) // Пример: 999.99
• &epn.tax - Transaction Tax (сумма налога) // Пример: 12.85
• &epn.shipping - Transaction Shipping (стоимость доставки) // Пример: 850.55
• &pi - Promotion ID (идентификатор рекламной акции) // Пример: PROMO_1234
• &pn - Promotion Name (название рекламной акции) // Пример: summer_sale
• &cn - Creative Name (название креатива) // Пример: summer_banner2
• &cs - Creative Slot (название рекламного места для объявления) // Пример: banner2_slot_1
• &lo - Location ID (Google Place IDs в Google Maps. Вероятно, унаследовано от Firebase, но нет уверенности насчет текущего использования в GA4) // Пример: ChIJiyj437sx3YAR9kUWC8QkLzQ

E-Commerce (Данные о товаре)

• &pr[0-9]{1,200} - Item (Объект, представленный в виде строки, который содержит информацию о товаре со всеми его параметрами) // Пример: pr1: id89~nmНоски Reebok ACT CORE CREW SOCK MH~pr699~brReebok~qt1~k0google_business_vertical~v0retail
• &id - Item ID (идентификатор или код товара) // Пример: 101
• &nm - Item Name (название товара) // Пример: Носки Reebok ACT CORE CREW SOCK MH
• &br - Item Brand (бренд товара) // Пример: Reebok
• &ca - Item Category Hierarchy 1 (категория верхнего уровня, к которой относится товар) // Пример: Clothes
• &ca2 - Item Category Hierarchy 2 (подкатегория, к которой относится товар) // Пример: Mens
• &ca3 - Item Category Hierarchy 3 (подкатегория, к которой относится товар) // Пример: Shirts
• &ca4 - Item Category Hierarchy 4 (подкатегория, к которой относится товар) // Пример: White
• &ca5 - Item Category Hierarchy 5 (подкатегория, к которой относится товар) // Пример: Sale

В Universal Analytics Item Category добавлялись в один параметр category, а в качестве разделителя использовалась косая черта (/). Пример: Одежда/Мужская одежда/Футболки. В Google Analytics 4 это все разделили на отдельные item_category:

• item_category: Одежда
• item_category1: Мужская одежда
• item_category2: Футболки
• и т.д.

Именно поэтому есть категории разного уровня - 1, 2, 3, 4, 5.

• &pr - Item Price (цена товара) // Пример: 699.99
• &qt - Item Quantity (количество единиц товара) // Пример: 2
• &va - Item Variant (вариант товара) // Пример: Yellow
• &cp - Item Coupon (код купона, связанного с товаром) // Пример: 50%OFF
• &ds - Item Discount (скидка (если есть), связанная с товаром) // Пример: 150.00
• &ln - Item List Name (название списка, в который входит товар) // Пример: Home Page
• &li - Item List ID (идентификатор списка, куда входит товар) // Пример: id-mens-123
• &lp - Item List Position (позиция товара в списке) // Пример: 9
• &af - Item Affiliation (товар, принадлещий магазину или филиалу. Вероятно, унаследовано от Firebase, но нет уверенности насчет текущего использования в GA4) // Пример: My Friend Shop

Без категории (данные отсутствуют)

• &_ee
• &gtm_up
• &_ecid
• &_uei
• &_gaz
• &_rdi - Redact Device Info
• &_geo - Geo Granularity

Создание запроса

Для того, чтобы упростить себе задачу формирования запроса и не ошибиться в итоговой конструкции Measurement Protocol, используйте специальный инструмент Event Builder. Он позволяет сформировать запрос, проверить его и сразу же с сайта (при необходимости) отправить данные о событии(ях) в Google Analytics 4.

Подробнее о том, как можно составить свой первый запрос, читайте здесь.

Вручную vs Автоматически

Как вы уже догадались, http-запросы практически никто не формирует вручную и никогда не передает через Event Builder (исключения - в ознакомительных целях или редкие случаи отправки), особенно если пользовательских данных много. Именно поэтому компании на своей стороне создают решения, которые позволяют автоматизировать процесс отправки таких запросов в Google Analytics при выполнении определенного действия.

Как правило, это запуск собственного сервера, его настройка, создание скриптов загрузки и установка частоты их выполнения. То есть классическая задача разработчика, который должен взять на себя все эти процессы. Либо же используются готовые интеграции и сервисы типа Albato и ApiX-Drive, с настройкой которых справится любой интернет-маркетолог.

Если вы используете Google Analytics как основной инструмент построения сквозной аналитики для своего проекта, вы можете отправлять информацию по изменению статусов сделок из CRM-системы в счетчик аналитики как раз с помощью Measurement Protocol.

Для этого требуется ряд настроек, в числе которых:

• настройка уникального идентификатора пользователя (Client ID) через специальный параметр (вручную);
• создание отдельного поля Client ID (вручную) и сохранение его значения в лиде/сделке CRM (автоматически);
• для каждого требуемого действия в CRM-системе сформировать свой http-запрос, который будет отправлять данные в Google Analytics после его срабатывания (автоматически);
• при изменении статуса сделки в CRM отправлять событие для конкретного пользователя в Google Analytics (автоматически).

Подробно эти и другие процессы сквозной аналитики разбираются в онлайн-курсе "Сквозная аналитика".