Ссылка на протокол измерений

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

Транспорт

Все данные должны отправляться безопасно с использованием 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 на полезную нагрузку запроса.

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

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

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

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

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

Имя параметра Описание

api_secret

 Обязательно . Секрет API из пользовательского интерфейса Google Analytics.

Находится в разделе Администрирование > Потоки данных > Выберите поток > Протокол измерений > Создать .

Конфиденциально для вашей организации. Рекомендуется регулярно обновлять, чтобы избежать чрезмерного спама.

Тело JSON POST

Ключ Тип Описание

user_id

 string

Необязательный . Уникальный идентификатор пользователя. Подробнее об этом идентификаторе см. в разделе «User-ID для кроссплатформенного анализа» . Может содержать только символы UTF-8.

timestamp_micros

 number

Необязательно . Временная метка Unix в микросекундах , а не в миллисекундах . Представляет время события. Следует устанавливать только для записи событий, произошедших в прошлом. Может быть переопределено user_property или временными метками событий. События можно датировать до 3 календарных дней в зависимости от часового пояса объекта.

user_properties

 object Необязательно . Пользовательские свойства для измерения.

user_data

 object Необязательно . Данные, предоставленные пользователем .
object Необязательно . Настройки согласия для запроса. Подробнее см. в разделе «Согласие» .

non_personalized_ads

 boolean Необязательно . Установите значение true чтобы указать, что данные пользователя не должны использоваться для персонализированной рекламы.

user_location

 object Необязательно . Задаёт географическую информацию для запроса в структурированном формате.

ip_override

 string Необязательно . IP-адрес, который Google Analytics использует для получения географической информации для запроса.

device

 object Необязательно. Задаёт информацию об устройстве для запроса в структурированном формате.

events[]

 array Обязательно . Массив элементов event . В одном запросе можно отправить до 25 событий. Все допустимые события см. в справочнике событий .

events[].name

 string Обязательно . Название события. Все варианты см. в разделе «События» .

events[].params

 object Необязательные параметры события. Рекомендуемые параметры для каждого события см. в разделе «События» и в разделе «Общие параметры событий» .

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

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

Ключ Тип Описание

session_id

 number Положительное число, идентифицирующее сеанс пользователя. Требуется для нескольких распространённых случаев использования . Должно соответствовать регулярному выражению ^\d+$ .

engagement_time_msec

 number Продолжительность взаимодействия пользователя с событием (в миллисекундах). Используйте значение, отражающее время взаимодействия пользователя с момента предыдущего события.

timestamp_micros

 number Время эпохи Unix для события (в микросекундах). Используйте этот параметр, чтобы переопределить временную метку события.

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

Ключ Тип Описание

ad_user_data

 string

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

Либо GRANTED , либо DENIED .

ad_personalization

 string

Необязательно . Согласие на персонализированную рекламу для пользователя.

Либо GRANTED , либо DENIED .

Географическая информация

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

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

Ключ Тип Описание

city

 string Необязательно . Название города . Если город находится в США, также укажите country_id и region_id , чтобы Google Analytics мог правильно сопоставить название города с его идентификатором .

region_id

 string Необязательно . Страна и подразделение по стандарту ISO 3166. Например, US-CA , US-AR , CA-BC , GB-LND , CN-HK .

country_id

 string Необязательно . Страна в формате ISO 3166-1 alpha-2 . Например, US , AU , ES , FR .

subcontinent_id

 string Необязательно . Субконтинент в формате ООН M49 . Например, 011 , 021 , 030 , 039 .

continent_id

 string Необязательно . Континент в формате UN M49 . Например, 002 , 019 , 142 , 150 .

Вот пример 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 Analytics извлекает географическую информацию из IP-адреса. Если вы отправляете user_location , Google Analytics игнорирует ip_override .

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

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

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

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

Ключ Тип Описание

category

 string Необязательно. Категория устройства. Например, desktop , tablet , mobile , smart TV .

language

 string Необязательно. Язык в формате ISO 639-1 . Например, en , en-US .

screen_resolution

 string Необязательно. Разрешение устройства в формате WIDTHxHEIGHT . Например, 1280x2856 , 1080x2340 .

operating_system

 string Необязательно. Операционная система или платформа. Например, MacOS .

operating_system_version

 string Необязательно. Версия операционной системы или платформы. Например, 13.5 .

model

 string Необязательно. Модель устройства. Например, Pixel 9 Pro , Samsung Galaxy S24 .

brand

 string Необязательно. Марка устройства. Например, Google , Samsung .

browser

 string Необязательно. Марка или тип браузера. Например, Chrome , Firefox .

browser_version

 string Необязательно. Версия браузера. Например, 136.0.7103.60 , 5.0 .

В следующем фрагменте показан пример настроек 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"
}

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

Пользовательские параметры

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

  • Пользовательские параметры, определяемые пользователем, могут быть включены в 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
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

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

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

  • 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_