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

На этой странице описаны транспортный механизм и параметры данных для Measurement Protocol.

Транспортная часть

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

Отправьте запрос на следующий адрес:

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

Если вы хотите, чтобы данные собирались в ЕС, используйте следующий адрес:

https://region1.google-analytics.com/mp/collect

Пример запроса POST:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

Замените PAYLOAD_DATA на полезную нагрузку запроса.

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

Полезная нагрузка

Полезная нагрузка состоит из двух частей:

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

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

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

Размер тела запроса POST в формате JSON должен быть менее 130 КБ.

Общие параметры событий

В Measurement Protocol есть следующие общие параметры событий:

Согласие

Атрибут consent задает типы согласия и состояния. Если не указать consent, Google Аналитика будет использовать настройки согласия из соответствующих онлайн-взаимодействий с клиентом или экземпляром приложения.

Информация о местоположении

Атрибуты user_location и ip_override содержат географическую информацию. Правило user_location имеет приоритет над правилом ip_override.

Ниже приведена структура поля user_location. Добавьте как можно больше атрибутов. Мы рекомендуем использовать как минимум country_id и region_id.

Ниже приведен пример запроса user_location.

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override – альтернатива user_location. Если вы отправите ip_override, Google Аналитика получит географическую информацию из IP-адреса. Если вы отправите user_location, Google Аналитика проигнорирует ip_override.

Если вы не передаете значения user_location или ip_override, Google Аналитика получает географическую информацию из событий с тегами, используя app_instance_id.

Google Аналитика применяет к запросу настройки детализации геоданных ресурса независимо от отправленной географической информации.

Информация об устройстве

Чтобы отправить информацию об устройстве, используйте поле device. Вот структура поля device. Укажите как можно больше атрибутов. Мы рекомендуем использовать не менее category.

Во фрагменте кода ниже приведен пример настроек device:

"device": {
  "category": "mobile",
  "language": "en",
  "screen_resolution": "1280x2856",
  "operating_system": "Android",
  "operating_system_version": "14",
  "model": "Pixel 9 Pro",
  "brand": "Google",
  "browser": "Chrome",
  "browser_version": "136.0.7103.60"
}

Независимо от того, указали вы device, Google Аналитика применяет к запросу настройки детализированных данных об устройствах ресурса.

Проверка

Атрибут validation_behavior определяет, как Measurement Protocol проверяет содержимое запроса.

• Проверка RELAXED отклоняет только запросы с неверным форматом. Она может принимать события и параметры с недопустимыми названиями полей или данными неправильного типа, но игнорирует параметры, которые превышают ограничения. По умолчанию в Measurement Protocol используется проверка RELAXED.
• ENFORCE_RECOMMENDATIONSПри проверке отклоняются события и параметры товаров, которые имеют неправильный тип или содержат параметры, превышающие ограничения. Кроме того, ENFORCE_RECOMMENDATIONS отклоняет любое событие или свойство пользователя с временной меткой, которая не относится к последним 72 часам.

Мы рекомендуем следующий подход:

• Используйте ENFORCE_RECOMMENDATIONS при проверке событий, чтобы получать как можно больше отзывов о потенциальных проблемах с вашими запросами.

  Вы также можете проверять запросы с помощью конструктора событий, поскольку при проверке запросов он указывает ENFORCE_RECOMMENDATIONS.

• Не указывайте validation_behavior, когда отправляете события, чтобы уменьшить количество данных, отклоняемых Measurement Protocol.

  Если при отправке определенного запроса вы хотите, чтобы строгая проверка была приоритетнее сбора данных, добавьте поле validation_behavior и задайте для него значение ENFORCE_RECOMMENDATIONS.

Специальные параметры

Вы можете включить специальные параметры на уровне пользователя, на уровне события и на уровне позиции в полезную нагрузку Measurement Protocol.

• Специальные параметры на уровне пользователя можно добавить в объект user_properties.
• Специальные параметры на уровне события можно добавить в объект events[].params.
• Специальные параметры на уровне позиции можно добавить в items.

Рекомендуемые параметры для некоторых событий

Для некоторых событий есть рекомендуемые параметры. Подробнее о параметрах, рекомендуемых для поддерживаемых событий…

Зарезервированные названия

Некоторые названия событий, параметров и свойств пользователей зарезервированы, и вы не можете их использовать:

Зарезервированные названия событий

Эти названия событий зарезервированы, и вы не можете их использовать:

• ad_activeview
• ad_click
• ad_exposure
• ad_query
• ad_reward
• adunit_exposure
• app_clear_data
• app_exception
• app_install
• app_remove
• app_store_refund
• app_update
• app_upgrade
• dynamic_link_app_open
• dynamic_link_app_update
• dynamic_link_first_open
• error
• firebase_campaign
• firebase_in_app_message_action
• firebase_in_app_message_dismiss
• firebase_in_app_message_impression
• first_open
• first_visit
• notification_dismiss
• notification_foreground
• notification_open
• notification_receive
• notification_send
• os_update
• session_start
• user_engagement

Кроме того, события ad_impression, in_app_purchase и screen_view разрешены только для потоков приложений.

Зарезервированные названия параметров

Эти названия параметров зарезервированы, и вы не можете их использовать:

• firebase_conversion

Названия параметров не могут начинаться со следующих префиксов:

• _ (underscore)
• firebase_
• ga_
• google_
• gtag.

Зарезервированные названия свойств пользователей

Эти названия свойств пользователей зарезервированы, и вы не можете их использовать:

• first_open_time
• first_visit_time
• last_deep_link_referrer
• user_id
• first_open_after_install

Также названия свойств пользователей не могут начинаться со следующих префиксов:

• _ (underscore)
• firebase_
• ga_
• google_