Как отправлять события Measurement Protocol в Google Аналитику

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

Идентификаторы и параметры, необходимые для запросов Measurement Protocol, зависят от того, отправляете ли вы события в поток сайта или поток приложения.

  • Для потоков данных сайта (обычно реализуемых с помощью gtag.js или Google Менеджера тегов) используйте measurement_id в URL запроса и client_id в теле JSON, чтобы идентифицировать экземпляр пользователя. Значение client_id должно совпадать с идентификатором, созданным тегом Google Аналитики на вашем сайте.
  • Для потоков приложений (с Firebase SDK) в URL запроса используется firebase_app_id, а в теле JSON – app_instance_id. Эти параметры предоставляются SDK Google Аналитики для Firebase.

В этом руководстве приведены примеры для обоих сценариев.

Основные компоненты запроса в зависимости от типа потока

Компонент Поток сайта (gtag.js/Менеджер тегов) Поток приложения (Firebase)
Параметр URL потока данных measurement_id firebase_app_id
Параметр URL секретного ключа API Обязательно Обязательно
Поле тела JSON с идентификатором устройства client_id app_instance_id

Выберите нужную платформу:

На этой вкладке приведены инструкции по отправке с сервера событий, связанных с действиями пользователей в потоке данных приложения, с помощью SDK Google Аналитики для Firebase. Обратите внимание, что в этих запросах используются firebase_app_id и app_instance_id.

Требования

Чтобы отправлять события с помощью Measurement Protocol, вам нужны определенные идентификаторы из ресурса Google Аналитики или проекта Firebase.

Секретный ключ API

api_secret используется для аутентификации запросов. Очень важно хранить этот секрет в тайне.

Чтобы создать секрет:

  1. Откройте Google Аналитику и перейдите в свой аккаунт и ресурс.
  2. В левом нижнем углу нажмите Администратор.
  3. В разделе Сбор и редактирование данных нажмите Потоки данных.
  4. Выберите поток данных сайта или приложения.
  5. Нажмите Секретные ключи API для Measurement Protocol.
  6. Нажмите Создать.
  7. Введите псевдоним для секрета и нажмите Создать.

  8. Скопируйте значение секрета.

Идентификатор приложения Firebase

firebase_app_id – это уникальный идентификатор вашего приложения Firebase. Он отличается от app_instance_id.

Чтобы найти идентификатор приложения Firebase, выполните следующие действия:

  1. Откройте проект в консоли Firebase.
  2. Нажмите на значок настроек рядом с пунктом Обзор проекта и выберите Настройки проекта.
  3. На вкладке Общие перейдите в раздел Ваши приложения.
  4. Выберите приложение для iOS или Android.
  5. Скопируйте значение в поле App ID (Идентификатор приложения).

Формат запроса

Measurement Protocol для Google Аналитики поддерживает только HTTP-запросы POST.

Для отправки события используйте следующий формат:

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

В параметрах запроса URL должны быть следующие данные (подробнее о том, как найти или создать эти значения, читайте в разделе Предварительные требования):

  • api_secret – секретный ключ API для аутентификации запроса.
  • firebase_app_id: идентификатор приложения Firebase.

Для Measurement Protocol необходимо предоставить тело запроса в формате тела запроса POST в формате JSON. Пример:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

В теле запроса необходимо указать app_instance_id, чтобы идентифицировать уникальную установку мобильного приложения. Обратите внимание, что это не то же самое, что firebase_app_id, который идентифицирует само приложение. Дополнительную информацию о параметре app_instance_id и о том, как получить его с помощью Firebase SDK, можно найти в справочной документации по app_instance_id.

session_start является зарезервированным названием события, однако при создании нового идентификатора session_id будет начат новый сеанс без необходимости отправлять session_start. Подробнее о том, как выполняется подсчет сеансов…

Попробовать

Вот пример того, как можно отправить несколько событий одновременно. В этом примере на сервер Google Аналитики отправляются события tutorial_begin и join_group, а также геоданные в поле user_location и информация об устройстве в поле device.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    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"
    }
  })
});

Формат firebase_app_id зависит от платформы (см. объекты и файлы конфигурации Firebase, раздел Идентификатор приложения).

Переопределить временную метку

Measurement Protocol использует первую временную метку, которую находит в следующем списке для каждого события и свойства пользователя в запросе:

  1. timestamp_micros события или свойства пользователя.
  2. timestamp_micros запроса
  3. Время, когда Measurement Protocol получает запрос.

В следующем примере отправляется временная метка на уровне запроса, которая применяется ко всем событиям и свойствам пользователей в запросе. В результате Measurement Protocol присваивает временную метку requestUnixEpochTimeInMicros событиям tutorial_begin и join_group и свойству пользователя customer_tier.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

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

  • tutorialBeginUnixEpochTimeInMicros для события tutorial_begin
  • customerTierUnixEpochTimeInMicros для свойства пользователя customer_tier
  • requestUnixEpochTimeInMicros для события join_group и свойства пользователя newsletter_reader.
{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

Проверка прошлых событий и свойств пользователей

События и свойства пользователей можно регистрировать задним числом (до 72 часов). Если значение timestamp_micros относится к периоду, который начался более 72 часов назад, Measurement Protocol принимает или отклоняет событие или свойство пользователя следующим образом:

  • Если параметр validation_behavior не задан или имеет значение RELAXED, Measurement Protocol принимает событие или свойство пользователя, но заменяет его временную метку на 72 часа назад.
  • Если для параметра validation_behavior задано значение ENFORCE_RECOMMENDATIONS, Measurement Protocol отклоняет событие или свойство пользователя.

События, отправленные с помощью Measurement Protocol и предназначенные для объединения или обработки вместе с событиями, собранными SDK Google Аналитики для Firebase или gtag.js, должны быть получены Google Аналитикой в течение 48 часов с момента исходной клиентской временной метки события. События, полученные позже, могут быть обработаны неправильно, особенно в целях атрибуции конверсий.

Ограничения

При отправке событий Measurement Protocol в Google Аналитику действуют следующие ограничения:

  • Для каждого ресурса можно отправлять не более 100 миллионов запросов, не связанных с конверсиями, в час. Запрос не считается запросом конверсии, если ни одно из событий в нем не является ключевым событием, для которого есть конверсия в Google Рекламе. Если вы превысите этот лимит, Measurement Protocol будет игнорировать все запросы, не связанные с конверсиями, для ресурса до конца часа.

  • Один запрос может содержать не больше 25 событий.

  • Одно событие может содержать не больше 25 параметров.

  • Одно событие может содержать не больше 25 свойств пользователей.

  • Название свойства пользователя может содержать не больше 24 символов.

  • Значение свойства пользователя может содержать не больше 36 символов.

  • Название события может содержать не больше 40 символов (буквы, цифры, знаки подчеркивания) и должно начинаться с буквы.

  • Названия параметров, включая параметры объектов, должны содержать не более 40 символов, могут включать только буквы и цифры, а также символы подчеркивания и должны начинаться с буквы.

  • Значение параметра может содержать не больше 100 символов для стандартного ресурса Google Аналитики и не больше 500 символов для ресурса Google Аналитики 360. Это касается и параметров объектов.

    Это ограничение не распространяется на параметры session_id и session_number, если их значения предоставляются соответствующими встроенными переменными Идентификатор сеанса Аналитики и Номер сеанса Аналитики в Google Менеджере тегов.

  • В параметрах объектов можно использовать не больше 10 специальных параметров.

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

  • События отслеживания приложений, отправляемые Measurement Protocol в Google Аналитику, не заполняют поисковые аудитории Google Рекламы для пользователей приложений.

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

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

В Measurement Protocol есть несколько зарезервированных названий, которые нельзя использовать для событий, параметров и свойств пользователей.

Ниже приведены названия событий, которые часто путают.

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