Эта страница переведена с помощью Cloud Translation API.

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

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

Транспорт

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

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

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

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

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

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

Имя параметра	Описание
`api_secret`	Required . The API Secret from the Google Analytics UI. Находится в разделе Администрирование > Потоки данных > Выберите поток > Протокол измерения > Создать . Конфиденциально для вашей организации. Рекомендуется регулярно обновлять, чтобы избежать чрезмерного спама.

`api_secret`

Required . The API Secret from the Google Analytics UI.

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

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

Тело JSON-запроса

Ключ	Тип	Описание
`user_id`	`string`	Необязательный параметр . Уникальный идентификатор пользователя. Дополнительную информацию об этом идентификаторе см. в разделе User-ID для кроссплатформенного анализа . Может содержать только символы UTF-8.
`timestamp_micros`	`number`	Необязательный параметр . Временная метка Unix, в микросекундах , а не в миллисекундах . Представляет время события. Следует устанавливать этот параметр только для записи событий, произошедших в прошлом. Может быть переопределен с помощью `user_property` или временных меток событий. События могут быть датированы задним числом до 72 часов.
`user_properties`	`object`	Optional . The user properties for the measurement.
`user_data`	`object`	Необязательно . Данные, предоставленные пользователем .
`consent`	`object`	Optional . Consent settings for the request. See the consent section for more information.
`non_personalized_ads`	`boolean`	Устарело: используйте поле `ad_personalization` в поле `consent` вместо него. Optional . Set to `true` to indicate the user's data shouldn't be used for personalized ads.
`user_location`	`object`	Optional . Sets the geographic information for the request in a structured format.
`ip_override`	`string`	Optional . IP address Google Analytics uses to derive geographic information for the request.
`device`	`object`	Optional. Sets the device information for the request in a structured format.
`validation_behavior`	`string`	Необязательный параметр. Задает поведение проверки для запроса. Either `RELAXED` or `ENFORCE_RECOMMENDATIONS` . Defaults to `RELAXED` if not specified.
`events[]`	`array`	Обязательно . Массив элементов `event` . В одном запросе можно отправить до 25 событий. Список всех допустимых событий см. в справочнике событий .
`events[].name`	`string`	Обязательно . Название мероприятия. Все варианты см. в разделе «Мероприятия» .
`events[].params`	`object`	Необязательный параметр . Параметры события. Рекомендуемые параметры для каждого события см. в разделе «События», а общие параметры событий — в разделе «Общие параметры событий» .

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

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

Ключ	Тип	Описание
`session_id`
`engagement_time_msec`	`number`	The duration of user engagement , in milliseconds, for the event. Use a value that reflects the amount of user engagement time since the preceding event.
`timestamp_micros`	`number`	The Unix epoch time, in microseconds, for the event. Use this parameter to override the timestamp of the event.

Согласие

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

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

Ключ	Тип	Описание
`ad_user_data`	`string`	Optional . Consent for sending user data from the request's events and user properties to Google for advertising purposes. Либо `GRANTED` , либо `DENIED` .
`ad_personalization`	`string`	Optional . Consent for personalized advertising for the user. Либо `GRANTED` , либо `DENIED` .

`ad_user_data`

string

Optional . Consent for sending user data from the request's events and user properties to Google for advertising purposes.

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

`ad_personalization`

string

Optional . Consent for personalized advertising for the user.

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

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

The user_location and ip_override attributes provide geographic information. user_location takes precedence over ip_override .

Here's the structure of the user_location field. Provide as many of the attributes as possible. We recommend country_id and region_id at a minimum.

Ключ	Тип	Описание
`city`	`string`	Optional . The city's name . If the city is in the US, also set `country_id` and `region_id` so Google Analytics can properly map the city name to a city ID .
`region_id`	`string`	Optional . The ISO 3166 country and subdivision. For example, `US-CA` , `US-AR` , `CA-BC` , `GB-LND` , `CN-HK` .
`country_id`	`string`	Optional . The country in ISO 3166-1 alpha-2 format . For example, `US` , `AU` , `ES` , `FR` .
`subcontinent_id`	`string`	Optional . The subcontinent in UN M49 format . For example, `011` , `021` , `030` , `039` .
`continent_id`	`string`	Optional . The continent in UN M49 format . For example, `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 .

If you don't send user_location or ip_override , Google Analytics derives geographic information from tagging events usingclient_id .

Google Analytics applies the property's granular location data settings to the request, regardless of the geographic information sent.

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

To send device information, use the device field. Here's the structure of the device field. Provide as many of the attributes as possible. We recommend category at a minimum.

Ключ	Тип	Описание
`category`	`string`	Необязательно. Категория устройства. Например, `desktop` , `tablet` , `mobile` , `smart TV` .
`language`	`string`	Необязательно. Язык в формате ISO 639-1 . Например, `en` , `en-US` .
`screen_resolution`	`string`	Необязательно. Разрешение устройства, заданное в формате `WIDTHxHEIGHT` . Например, `1280x2856` , `1080x2340` .
`operating_system`	`string`	Optional. The operating system or platform. For example, `MacOS` .
`operating_system_version`	`string`	Optional. The version of the operating system or platform. For example, `13.5` .
`model`	`string`	Необязательно. Модель устройства. Например, `Pixel 9 Pro` , `Samsung Galaxy S24` .
`brand`	`string`	Необязательно. Марка устройства. Например, `Google` , `Samsung` .
`browser`	`string`	Необязательно. Марка или тип браузера. Например, `Chrome` , `Firefox` .
`browser_version`	`string`	Optional. The version of the browser. For example, `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 применяет к запросу подробные настройки данных об устройстве, указанные для данного ресурса.

Поведение проверки

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

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

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

Используйте ENFORCE_RECOMMENDATIONS при проверке событий , чтобы получить как можно больше информации о потенциальных проблемах с вашими запросами.
Также можно проверять запросы с помощью Event Builder , поскольку при проверке запросов он указывает ENFORCE_RECOMMENDATIONS .
Не указывайте validation_behavior при отправке событий , чтобы минимизировать количество данных, отклоняемых протоколом Measurement Protocol.
Если вы хотите отдать приоритет строгой проверке данных перед их сбором при отправке конкретного запроса, добавьте поле validation_behavior и установите для него значение ENFORCE_RECOMMENDATIONS .

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

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

Пользовательские параметры, заданные в рамках пользовательского интерфейса, могут быть включены в 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_

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

Транспорт

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

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

api_secret

Тело JSON-запроса

user_id

timestamp_micros

user_properties

user_data

consent

non_personalized_ads

user_location

ip_override

device

validation_behavior

events[]

events[].name

events[].params

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

session_id

engagement_time_msec

timestamp_micros

Согласие

ad_user_data

ad_personalization

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

city

region_id

country_id

subcontinent_id

continent_id

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

category

language

screen_resolution

operating_system

operating_system_version

model

brand

browser

browser_version

Поведение проверки

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

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

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

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

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

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

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

`api_secret`

`user_id`

`timestamp_micros`

`user_properties`

`user_data`

`consent`

`non_personalized_ads`

`user_location`

`ip_override`

`device`

`validation_behavior`

`events[]`

`events[].name`

`events[].params`

`session_id`

`engagement_time_msec`

`timestamp_micros`

`ad_user_data`

`ad_personalization`

`city`

`region_id`

`country_id`

`subcontinent_id`

`continent_id`

`category`

`language`

`screen_resolution`

`operating_system`

`operating_system_version`

`model`

`brand`

`browser`

`browser_version`