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

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

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

Форматировать запрос

Протокол измерений Google Analytics поддерживает только запросы HTTP POST .

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

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

В URL-адресе запроса необходимо указать следующее:

  • api_secret : API SECRET , сгенерированный в пользовательском интерфейсе Google Analytics.

    Чтобы создать новый секрет, перейдите в раздел Администрирование > Сбор и изменение данных > Потоки данных > выберите свой поток > Секреты API протокола измерений > Создать .

  • firebase_app_id : идентификатор приложения Firebase, который можно найти в консоли Firebase в разделе «Настройки проекта» > «Общие» > «Ваши приложения» > «Идентификатор приложения» .

    firebase_app_id и app_instance_id — это не одно и то же. firebase_app_id идентифицирует ваше приложение, тогда как app_instance_id идентифицирует отдельную установку приложения.

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

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

Хотя 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",
  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 события или свойства пользователя.
  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 в Google Analytics действуют следующие ограничения:

  • Запросы могут содержать максимум 25 событий.
  • События могут иметь максимум 25 параметров.
  • События могут иметь максимум 25 пользовательских свойств.
  • Имена свойств пользователя должны содержать не более 24 символов.
  • Значения свойств пользователя должны содержать не более 36 символов.
  • Названия событий должны содержать не более 40 символов, могут содержать только буквенно-цифровые символы и символы подчеркивания и должны начинаться с буквенного символа.
  • Имена параметров, включая параметры элементов, должны содержать не более 40 символов, могут содержать только буквенно-цифровые символы и символы подчеркивания и должны начинаться с буквенного символа.
  • Значения параметров, включая значения параметров элементов, должны содержать не более 100 символов для стандартного свойства Google Analytics и не более 500 символов для свойства Google Analytics 360.
  • Параметры элемента могут иметь максимум 10 пользовательских параметров.
  • Тело сообщения должно быть меньше 130 КБ.
  • Временная метка должна быть в пределах последних 72 часов. Подробнее см. в разделе «Поведение проверки для прошлых событий» .
  • События App Measurement Protocol, отправляемые в Google Analytics, не заполняют поисковую аудиторию в Google Ads для пользователей приложения.

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