Wysyłaj zdarzenia Measurement Protocol do Google Analytics

Z tego przewodnika dowiesz się, jak wysyłać zdarzenia Measurement Protocol z Google Analytics z sieci i strumieni danych z aplikacji na serwer Google Analytics, aby móc wyświetlać zdarzenia Measurement Protocol w raportach Google Analytics.

Wybierz platformę, którą chcesz zobaczyć w tym przewodniku:

Formatowanie żądania

Platforma Google Analytics Measurement Protocol obsługuje tylko żądania HTTP POST.

Aby wysłać zdarzenie, użyj tego formatu:

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

PAYLOAD_DATA

W adresie URL żądania musisz podać te parametry:

  • api_secret: TAJNY KLUCZ API wygenerowany w interfejsie Google Analytics.

    Aby utworzyć nowy obiekt tajny, kliknij kolejno Administracja > Zbieranie i modyfikowanie danych > Strumienie danych > wybierz swój strumień > Tajne klucze API Measurement Protocol > Utwórz.

  • firebase_app_id: identyfikator aplikacji Firebase, który znajdziesz w konsoli Firebase w sekcji Ustawienia projektu > Ogólne > Twoje aplikacje > Identyfikator aplikacji.

    firebase_app_id nie jest tym samym co app_instance_id. firebase_app_id identyfikuje Twoją aplikację, a app_instance_id – pojedynczą instalację aplikacji.

W przypadku Measurement Protocol musisz podać treść żądania w formacie JSON POST. Oto przykład:

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

Chociaż session_start to zarezerwowana nazwa zdarzenia, utworzenie nowego parametru session_id powoduje utworzenie nowej sesji bez konieczności wysyłania parametru session_start. Dowiedz się, jak zliczane są sesje.

Wypróbuj

Oto przykład, którego możesz użyć do wysyłania wielu zdarzeń naraz. Ten przykład wysyła zdarzenie tutorial_begin i zdarzenie join_group na serwer Google Analytics, zawiera informacje geograficzne za pomocą pola user_location oraz informacje o urządzeniu za pomocą pola 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"
    }
  })
});

Format firebase_app_id zależy od platformy. Więcej informacji znajdziesz w sekcji Identyfikator aplikacji w plikach i obiektach konfiguracji Firebase.

Zastąpienie sygnatury czasowej

W przypadku każdego zdarzenia i właściwości użytkownika w żądaniu Measurement Protocol używa pierwszej sygnatury czasowej, którą znajdzie na tej liście:

  1. timestamp_micros zdarzenia lub właściwości użytkownika.
  2. timestamp_micros żądania.
  3. Czas, w którym Measurement Protocol otrzyma żądanie.

Ten przykład wysyła sygnaturę czasową na poziomie żądania, która ma zastosowanie do wszystkich zdarzeń i właściwości użytkownika w żądaniu. W rezultacie Measurement Protocol przypisuje sygnaturę czasową requestUnixEpochTimeInMicros do zdarzeń tutorial_begin i join_group oraz do właściwości użytkownika customer_tier.

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

Ten przykład wysyła sygnaturę czasową na poziomie żądania, sygnaturę czasową na poziomie zdarzenia i sygnaturę czasową na poziomie właściwości użytkownika. W rezultacie Measurement Protocol przypisuje te sygnatury czasowe:

  • tutorialBeginUnixEpochTimeInMicros do zdarzenia tutorial_begin.
  • customerTierUnixEpochTimeInMicros do właściwości użytkownika customer_tier.
  • requestUnixEpochTimeInMicros do zdarzenia join_group i właściwości użytkownika 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"
    }
  }
}

Działanie walidacji w przypadku zdarzeń i właściwości użytkownika z przeszłości

Zdarzenia i właściwości użytkownika można datować wstecznie maksymalnie o 72 godziny. Jeśli wartość timestamp_micros jest wcześniejsza niż 72 godziny temu, Measurement Protocol akceptuje lub odrzuca zdarzenie lub właściwość użytkownika w ten sposób:

  • Jeśli validation_behavior nie jest ustawiony lub ma wartość RELAXED, Measurement Protocol akceptuje zdarzenie lub właściwość użytkownika, ale zastępuje jego sygnaturę czasową sygnaturą sprzed 72 godzin.
  • Jeśli validation_behavior ma wartość ENFORCE_RECOMMENDATIONS, Measurement Protocol odrzuca zdarzenie lub właściwość użytkownika.

Zdarzenia wysyłane za pomocą Measurement Protocol, które mają być łączone lub przetwarzane razem ze zdarzeniami zbieranymi przez pakiet SDK Google Analytics dla Firebase lub gtag.js, powinny zostać odebrane przez Google Analytics w ciągu 48 godzin od pierwotnej sygnatury czasowej zdarzenia po stronie klienta. Zdarzenia otrzymane później mogą nie być przetwarzane zgodnie z oczekiwaniami, zwłaszcza w przypadku takich celów jak atrybucja konwersji.

Ograniczenia

W przypadku wysyłania zdarzeń Measurement Protocol do Google Analytics obowiązują te ograniczenia:

  • Żądania mogą zawierać maksymalnie 25 zdarzeń.
  • Zdarzenia mogą zawierać maksymalnie 25 parametrów.
  • Zdarzenia mogą obejmować maksymalnie 25 właściwości użytkownika.
  • Nazwa właściwości użytkownika może mieć maksymalnie 24 znaki.
  • Wartości właściwości użytkownika mogą się składać z maksymalnie 36 znaków.
  • Nazwy zdarzeń mogą mieć maksymalnie 40 znaków oraz zawierać tylko znaki alfanumeryczne i znaki podkreślenia. Muszą się też zaczynać literą.
  • Nazwy parametrów (w tym parametrów produktów) mogą mieć maksymalnie 40 znaków oraz zawierać tylko znaki alfanumeryczne i znaki podkreślenia. Muszą się też zaczynać literą.

  • Wartości parametrów (w tym wartości parametrów produktów) mogą mieć maksymalnie 100 znaków w przypadku standardowej usługi w Google Analytics i 500 znaków w przypadku usługi w Google Analytics 360.

    Ten limit nie dotyczy parametrów session_id i session_number gdy ich wartości są podawane przez odpowiednie wbudowane zmienne Identyfikator sesji Analytics i Numer sesji Analytics w Menedżerze tagów Google.

  • Parametry produktów mogą mieć maksymalnie 10 parametrów niestandardowych.

  • Treść posta musi być mniejsza niż 130 kB.

  • Zdarzenia Measurement Protocol aplikacji wysyłane do Google Analytics nie powodują wypełniania odbiorców wyszukiwania w Google Ads w przypadku użytkowników aplikacji.

  • Niektóre nazwy zdarzeń, parametrów i właściwości użytkownika są zarezerwowane i nie można ich używać. Więcej informacji znajdziesz w sekcji Nazwy zarezerwowane szczegóły.

Nazwy zarezerwowane

Measurement Protocol ma kilka nazw zarezerwowanych, których nie można używać w przypadku zdarzeń, parametrów ani właściwości użytkownika.

Te nazwy zdarzeń często powodują nieporozumienia:

Dodatkowe wymagania dotyczące każdego przypadku użycia znajdziesz w sekcji Typowe przypadki użycia.