Как отправлять события 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/GTM)	Поток данных приложения (Firebase)
Параметр URL потока данных	measurement_id	firebase_app_id
Параметр URL для секретного ключа API	Обязательно	Обязательно
Поле идентификатора устройства в теле JSON	client_id	app_instance_id

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

Firebase gtag.js

На этой вкладке приведены инструкции по отправке событий с сервера, которые связаны с действиями пользователей в потоке данных приложения, с помощью 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. Скопируйте значение секрета.

   Важно! Символ api_secret виден только вам. Не раскрывайте его в клиентском коде сайта или приложения.

   • Риск для безопасности. Если api_secret будет доступен посторонним лицам, они смогут отправлять в ваш ресурс Google Аналитики произвольные данные или спам, что может привести к искажению отчетов.
   • Правильное использование. Measurement Protocol в первую очередь предназначен для серверной или доверенной среды (например, офлайн-систем или обмена данными между серверами).
   • Отслеживание на стороне клиента. Если вам нужно отправлять события непосредственно из браузера, используйте тег Google (gtag.js) или Google Менеджер тегов.
   • Расширения Chrome. В расширениях Chrome с Manifest V3 нельзя загружать удаленный код, например gtag.js. В этом случае рекомендуется использовать Measurement Protocol. Подробнее о том, как использовать Google Аналитику в расширениях Chrome…

Идентификатор приложения 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

Совет. Если вы хотите, чтобы данные собирались в ЕС, измените HOST в примере на region1.google-analytics.com.

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

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

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

  {
   "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. Подробнее о том, как выполняется подсчет сеансов…

Попробовать

Примечание. В приведенных ниже примерах используется API fetch, предназначенный для серверных или доверенных сред (например, Node.js или серверной части). Их не следует использовать в клиентском коде (браузера), так как это может привести к раскрытию api_secret.

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

Примечание. Ограничения функций 360 описаны в статье Google Аналитика 360.

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

  Важно! Это ограничение не распространяется на ресурсы Google Аналитики 360.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• screen_view: это событие допустимо только для потоков приложений. Для веб-трансляций используйте page_view.
• ad_impression: это событие допустимо только для потоков приложений.
• in_app_purchase: это событие допустимо только для потоков приложений. Для потоков данных с сайта используйте событие purchase.

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