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

В этом руководстве объясняется, как отправлять события протокола Measurement Protocol ( Measurement Protocol) для веб- и мобильных приложений на сервер Google Analytics, чтобы вы могли просматривать эти события в отчетах Google Analytics .

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

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

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

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

Компонент	Веб-трансляция (gtag.js/GTM)	App stream (Firebase)
Параметр URL потока данных	measurement_id	firebase_app_id
Параметр секретного URL API	Необходимый	Необходимый
Поле JSON-тела с идентификатором устройства	client_id	app_instance_id

Выберите платформу, которую хотите увидеть в этом руководстве:

Firebase gtag.js

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

Предварительные требования

Для отправки событий с использованием протокола Measurement Protocol вам потребуются определенные идентификаторы из вашего ресурса Google Analytics или проекта Firebase.

Секрет API

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

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

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

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

   Важно: параметр api_secret является приватным. Не раскрывайте его в клиентском коде вашего веб-сайта или приложения.

   • Риск безопасности: раскрытие параметра api_secret позволяет неавторизованным лицам отправлять произвольные или спам-данные в ваш ресурс Google Analytics, что может исказить ваши отчеты.
   • Правильное использование: Протокол измерения (Measurement Protocol) в первую очередь предназначен для серверной части или доверенных сред (например, автономных систем или обмена данными между серверами).
   • Отслеживание на стороне клиента: Если вам необходимо отправлять события непосредственно из веб-браузера, используйте тег Google (gtag.js) или Google Tag Manager .
   • Расширения Chrome: Для расширений Chrome Manifest V3 невозможно загрузить удаленный код, например gtag.js В этом случае рекомендуется использовать протокол Measurement Protocol. См. раздел «Использование Google Analytics в расширениях Chrome» .

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

Параметр firebase_app_id идентифицирует ваше приложение Firebase. Он отличается от app_instance_id .

Чтобы найти идентификатор вашего приложения Firebase:

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

Отформатируйте запрос

Протокол измерения Google Analytics поддерживает только 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 . Вот пример:

  {
   "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 Analytics отправляются события 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 .

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

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

1. timestamp_micros значение параметра event или user.
2. timestamp_micros запроса.
3. Время получения запроса протоколом измерения.

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

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

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

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

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

Ограничения

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

Примечание: Информацию об ограничениях функций Google Analytics 360 см. в разделе Google Analytics 360 .

• В запросе может быть максимум 25 событий.
• События могут содержать максимум 25 параметров.
• В рамках мероприятия может быть указано максимум 25 пользовательских свойств.
• Названия свойств пользователя должны содержать не более 24 символов.
• Значения свойств пользователя должны содержать не более 36 символов.
• Названия мероприятий не должны содержать более 40 символов, могут включать только буквенно-цифровые символы и символы подчеркивания, а также должны начинаться с буквы.
• Названия параметров, включая параметры элементов, должны содержать не более 40 символов, могут содержать только буквенно-цифровые символы и символы подчеркивания, а также должны начинаться с буквы.

• Значения параметров, включая значения параметров элементов, должны быть не более 100 символов для стандартного ресурса Google Analytics и не более 500 символов для ресурса Google Analytics 360.

  Это ограничение не распространяется на параметры session_id и session_number , если их значения предоставляются соответствующими встроенными переменными Analytics Session ID и Analytics Session Number в Google Tag Manager.

• Параметры элемента могут содержать максимум 10 пользовательских параметров.

• Размер тела сообщения должен быть менее 130 кБ.

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

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

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

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

Следующие названия событий часто вызывают путаницу:

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

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