Wysyłaj zdarzenia Measurement Protocol do Google Analytics

Z tego przewodnika dowiesz się, jak wysyłać zdarzenia Measurement Protocol w Google Analytics ze strumieni danych z sieci i aplikacji na serwer Google Analytics, aby móc wyświetlać zdarzenia Measurement Protocol 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 skonfigurowanych 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. Wartość client_id powinna być zgodna z identyfikatorem wygenerowanym przez tag Google Analytics w Twojej witrynie.
  • W przypadku strumieni danych z aplikacji (z pakietem SDK Firebase) używasz w adresie URL żądania parametru firebase_app_id i w treści JSON parametru app_instance_id, które są dostarczane przez pakiet SDK Google Analytics dla Firebase.

W tym przewodniku znajdziesz przykłady obu tych scenariuszy.

Komponenty żądania klucza 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żytkowników w strumieniu danych z aplikacji, za pomocą pakietu SDK Google Analytics dla Firebase. Pamiętaj, że te prośby korzystają z firebase_app_id i app_instance_id.

Wymagania wstępne

Aby wysyłać zdarzenia za pomocą Measurement Protocol, musisz mieć określone identyfikatory z usługi w Google Analytics lub projektu w Firebase.

Tajny klucz API

api_secret służy do uwierzytelniania Twoich żądań. Konieczne jest zachowanie poufności tego klucza.

Aby utworzyć nowy obiekt tajny:

  1. Otwórz Google Analytics i przejdź do swojego 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 nazwę obiektu tajnego i kliknij Utwórz.

  8. Skopiuj wartość obiektu tajnego.

Identyfikator aplikacji w Firebase

Symbol firebase_app_id identyfikuje Twoją aplikację w Firebase. Nie jest to to samo co app_instance_id.

Aby znaleźć identyfikator aplikacji w Firebase:

  1. Otwórz projekt w konsoli Firebase.
  2. Kliknij ikonę koła zębatego obok pozycji 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ść Identyfikator aplikacji.

Formatowanie żądania

Protokół Measurement Protocol w Google Analytics obsługuje tylko żądania HTTPPOST.

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 wartości (szczegółowe informacje o tym, jak je znaleźć lub utworzyć, znajdziesz w sekcji Wymagania wstępne):

  • api_secret: tajny klucz API do uwierzytelniania żądania.
  • firebase_app_id: Identyfikator aplikacji w Firebase.

W przypadku protokołu pomiarowego musisz podać treść żądania w formacie treści żądania POST w formacie JSON. Oto przykład:

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

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

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ń jednocześnie. 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 firebase_app_id zależy od platformy. Więcej informacji znajdziesz w sekcji Identyfikator aplikacji w artykule Pliki i obiekty konfiguracyjne Firebase.

Zastąp sygnaturę czasową

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

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

W tym przykładzie wysyłany jest sygnatura czasowa 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 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"
    }
  }
}

W tym przykładzie wysyłana jest sygnatura czasowa na poziomie żądania, sygnatura czasowa na poziomie zdarzenia i sygnatura czasowa na poziomie właściwości użytkownika. W rezultacie protokół pomiarowy przypisuje te sygnatury czasowe:

  • tutorialBeginUnixEpochTimeInMicros na wydarzenie tutorial_begin
  • customerTierUnixEpochTimeInMicros w przypadku customer_tier właściwości użytkownika
  • requestUnixEpochTimeInMicros w przypadku 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"
    }
  }
}

Weryfikacja 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, Measurement Protocol akceptuje lub odrzuca zdarzenie lub właściwość użytkownika w ten sposób:

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

Zdarzenia wysyłane za pomocą platformy Measurement Protocol, które mają być łączone lub przetwarzane w połączeniu ze zdarzeniami zbieranymi przez pakiet SDK Google Analytics dla Firebase lub tag gtag.js, powinny być odbierane 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 na potrzeby takie jak atrybucja konwersji.

Ograniczenia

Wysyłanie zdarzeń Measurement Protocol do Google Analytics podlega tym ograniczeniom:

  • W przypadku każdej usługi możesz wysyłać maksymalnie 100 milionów żądań niezwiązanych z konwersją na godzinę. Żądanie jest żądaniem bez konwersji, jeśli żadne ze zdarzeń w żądaniu nie jest kluczowym zdarzeniem, dla którego istnieje konwersja w Google Ads. Jeśli przekroczysz ten limit, protokół pomiarowy będzie dyskretnie ignorować wszystkie żądania dotyczące usługi, które nie są związane z konwersjami, do końca 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 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 produktu mogą mieć maksymalnie 10 parametrów niestandardowych.

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

  • Zdarzenia Measurement Protocol wysyłane do Google Analytics w ramach pomiaru danych o korzystaniu z aplikacji nie wypełniają w Google Ads list odbiorców z sieci wyszukiwania dla 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 Zarezerwowane nazwy.

Zarezerwowane nazwy

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 są mylone:

Dodatkowe wymagania dotyczące poszczególnych przypadków użycia znajdziesz w sekcji Typowe przypadki użycia.