Wysyłaj zdarzenia Measurement Protocol do Google Analytics

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

Identyfikatory i parametry wymagane w przypadku żądań Measurement Protocol zależą od tego, czy wysyłasz zdarzenia do strumienia danych z sieci czy do strumienia danych z aplikacji.

  • W przypadku strumieni danych z sieci (zwykle instrumentowanych za pomocą tagu gtag.js lub Menedżera tagów Google) do identyfikowania instancji użytkownika używasz parametru measurement_id w adresie URL żądania i parametru client_id w treści JSON. Parametr client_id powinien być zgodny z identyfikatorem wygenerowanym przez tag Google Analytics w Twojej witrynie.
  • W przypadku strumieni danych z aplikacji (instrumentowanych za pomocą pakietu SDK Firebase) używasz parametru firebase_app_id w adresie URL żądania i parametru app_instance_id w treści JSON, które są udostępniane przez pakiet SDK Google Analytics dla Firebase.

W tym przewodniku znajdziesz przykłady obu tych scenariuszy.

Główne komponenty żądania według typu strumienia

Komponent Strumień danych z sieci (gtag.js/GTM) Strumień danych z aplikacji (Firebase)
Parametr adresu URL strumienia danych measurement_id firebase_app_id
Parametr adresu URL tajnego klucza API Wymagane Wymagane
Pole treści JSON identyfikatora urządzenia client_id app_instance_id

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

Na tej karcie znajdziesz instrukcje wysyłania z serwera zdarzeń, które są powiązane z aktywnością użytkownika w strumieniu danych z aplikacji za pomocą pakietu SDK Google Analytics dla Firebase. Pamiętaj, że te żądania używają parametrów firebase_app_id i app_instance_id.

Wymagania wstępne

Aby wysyłać zdarzenia za pomocą Measurement Protocol, potrzebujesz określonych identyfikatorów z usługi w Google Analytics lub projektu w Firebase.

Klucz tajny API

Parametr api_secret służy do uwierzytelniania żądań. Koniecznie zachowaj ten klucz w tajemnicy.

Aby utworzyć nowy klucz tajny:

  1. Otwórz Google Analytics i przejdź do konta i usługi.
  2. W lewym dolnym rogu kliknij Administracja.
  3. W sekcji Zbieranie i modyfikowanie danych kliknij Strumienie danych.
  4. Wybierz strumień danych z sieci lub aplikacji.
  5. Kliknij Tajne klucze API platformy Measurement Protocol.
  6. Kliknij Utwórz.
  7. Wpisz pseudonim klucza tajnego i kliknij Utwórz.

  8. Skopiuj wartość klucza tajnego.

Identyfikator aplikacji Firebase

Parametr firebase_app_id identyfikuje Twoją aplikację w Firebase. Nie jest on taki sam jak parametr app_instance_id.

Aby znaleźć identyfikator aplikacji Firebase:

  1. Otwórz projekt w konsoli Firebase.
  2. Kliknij ikonę koła zębatego obok opcji Przegląd projektu i wybierz Ustawienia projektu.
  3. Na karcie Ogólne przejdź do sekcji Twoje aplikacje.
  4. Wybierz konkretną aplikację na iOS lub Androida.
  5. Skopiuj wartość identyfikatora aplikacji.

Formatowanie żądania

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

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

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

W parametrach zapytania adresu URL żądania musisz podać te parametry (szczegółowe informacje o tym, jak znaleźć lub utworzyć te wartości, znajdziesz w sekcji Wymagania wstępne):

  • api_secret: klucz tajny API służący do uwierzytelniania żądania.
  • firebase_app_id: identyfikator aplikacji Firebase.

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
        }
      }
   ]
  }

Aby zidentyfikować unikalną instalację aplikacji mobilnej, musisz podać w treści żądania parametr app_instance_id. Pamiętaj, że różni się on od parametru firebase_app_id, który identyfikuje samą aplikację. Więcej informacji o parametrze app_instance_id i o tym, jak go pobrać za pomocą pakietu SDK Firebase, znajdziesz w dokumentacji referencyjnej app_instance_id.

Chociaż session_start jest zarezerwowaną nazwą zdarzenia, utworzenie nowego parametru session_id powoduje utworzenie nowej sesji bez konieczności wysyłania parametru session_start. Dowiedz się, jak są liczone sesje.

Wypróbuj

Oto przykład, którego możesz użyć do wysyłania kilku zdarzeń naraz. Ten przykład wysyła do serwera Google Analytics zdarzenie tutorial_begin i zdarzenie join_group, 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 parametru firebase_app_id zależy od platformy. Więcej informacji znajdziesz w sekcji Identyfikator aplikacji w artykule Pliki i obiekty konfiguracyjne Firebase.

Zastępowanie 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. Parametr timestamp_micros zdarzenia lub właściwości użytkownika.
  2. Parametr 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ść parametru 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 parametr 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 parametr 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 tag 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:

  • W przypadku każdej usługi możesz wysyłać maksymalnie 100 milionów żądań niezwiązanych z konwersją na godzinę. Żądanie jest żądaniem niezwiązanym z konwersją, jeśli żadne ze zdarzeń w żądaniu nie jest kluczowym zdarzeniem, dla którego w Google Ads występuje konwersja. Jeśli przekroczysz ten limit, Measurement Protocol będzie ignorować wszystkie żądania niezwiązane z konwersją w przypadku tej usługi przez pozostałą część godziny.

  • Żą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 w Google Ads list odbiorców z wyszukiwarki 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 zarezerwowanych nazw, 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 artykule Typowe przypadki użycia.