Как отправлять события 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

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

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

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

В параметрах запроса 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 . Разберитесь, как подсчитываются сессии .

Попробуйте!

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

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

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

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

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

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

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

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