Z tego przewodnika dowiesz się, jak wysyłać do serwera Google Analytics zdarzenia ze strumieni danych z sieci i aplikacji za pomocą Google Analytics Measurement Protocol, 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 instrumentowanych za pomocą tagu gtag.js lub Menedżera tagów Google) do identyfikowania instancji użytkownika używasz parametru
measurement_idw adresie URL żądania i parametruclient_idw treści JSON.client_idpowinien 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_idw adresie URL żądania i parametruapp_instance_idw treści JSON, które są dostarczane przez pakiet SDK Google Analytics dla Firebase.
W tym przewodniku znajdziesz przykłady obu tych scenariuszy.
Kluczowe 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 interfejsu 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 żądania używają 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.
Tajny klucz API
api_secret służy do uwierzytelniania żądań. Kluczowe jest zachowanie tego obiektu tajnego w poufności.
Aby utworzyć nowy obiekt tajny:
- Otwórz Google Analytics i przejdź do swojego konta oraz usługi.
- W lewym dolnym rogu kliknij Administracja.
- W sekcji Zbieranie i modyfikowanie danych kliknij Strumienie danych.
- Wybierz strumień danych z sieci lub aplikacji.
- Kliknij Tajne klucze API platformy Measurement Protocol.
- Kliknij Utwórz.
- Wpisz nazwę obiektu tajnego i kliknij Utwórz.
Skopiuj wartość obiektu tajnego.
Identyfikator aplikacji w Firebase
firebase_app_id identyfikuje Twoją aplikację w Firebase. Nie jest to to samo co app_instance_id.
Aby znaleźć identyfikator aplikacji w Firebase:
- Otwórz projekt w konsoli Firebase.
- Kliknij ikonę koła zębatego obok opcji Przegląd projektu i wybierz Ustawienia projektu.
- Na karcie Ogólne przejdź do sekcji Twoje aplikacje.
- Wybierz konkretną aplikację na iOS lub Androida.
- Skopiuj wartość App ID (Identyfikator aplikacji).
Formatowanie żądania
Platforma Measurement Protocol w 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: tajny klucz API do uwierzytelniania żądania.firebase_app_id: identyfikator aplikacji w Firebase.
W przypadku Measurement Protocol musisz podać treść żądania w formacie treści POST 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ę on od 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 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 wysłania wielu zdarzeń naraz. Ten przykład wysyła zdarzenie tutorial_begin i zdarzenie join_group na serwer Google Analytics, zawiera informacje geograficzne w polu user_location oraz informacje o urządzeniu w polu 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. Zobacz Identyfikator aplikacji w sekcji Pliki i obiekty konfiguracji 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 każdej właściwości użytkownika w żądaniu:
timestamp_microszdarzenia lub właściwości użytkownika.timestamp_microsprośby.- Czas, w którym Measurement Protocol otrzymuje żądanie.
Ten przykładowy kod wysyła sygnaturę czasową na poziomie żądania, która dotyczy wszystkich zdarzeń i właściwości użytkownika w żądaniu. W efekcie 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"
}
}
}
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 Measurement Protocol przypisuje te sygnatury czasowe:
tutorialBeginUnixEpochTimeInMicrosza wydarzenietutorial_begincustomerTierUnixEpochTimeInMicrosdla właściwości użytkownikacustomer_tierrequestUnixEpochTimeInMicrosdla zdarzeniajoin_groupi właściwości użytkownikanewsletter_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"
}
}
}
Sposób sprawdzania poprawności zdarzeń i właściwości użytkownika z przeszłości
Zdarzenia i właściwości użytkownika mogą być datowane wstecznie do 72 godzin. Jeśli wartość timestamp_micros jest wcześniejsza niż 72 godziny temu, Measurement Protocol akceptuje lub odrzuca zdarzenie bądź właściwość użytkownika w następujący sposób:
- Jeśli parametr
validation_behaviornie jest ustawiony lub jest ustawiony naRELAXED, Measurement Protocol akceptuje zdarzenie lub właściwość użytkownika, ale zastępuje sygnaturę czasową wartością sprzed 72 godzin. - Jeśli parametr
validation_behaviorma wartość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 razem 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 zostać przetworzone zgodnie z oczekiwaniami, zwłaszcza w przypadku atrybucji konwersji.
Ograniczenia
Wysyłanie zdarzeń Measurement Protocol do Google Analytics podlega tym ograniczeniom:
Możesz wysyłać maksymalnie 100 mln żądań niebędących konwersjami na godzinę w przypadku każdej usługi. Żą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, Measurement Protocol będzie dyskretnie ignorować wszystkie żądania niezwiązane z konwersjami dotyczące danej 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_idisession_number, gdy ich wartości są podawane przez odpowiednie zmienne wbudowane Identyfikator sesji Analytics i Numer sesji Analytics w Menedżerze tagów Google.Parametry produktu mogą zawierać maksymalnie 10 parametrów niestandardowych.
Treść posta musi być mniejsza niż 130 kB.
Zdarzenia Measurement Protocol dotyczące pomiaru danych o korzystaniu z aplikacji wysyłane do Google Analytics nie wypełniają list odbiorców w sieci 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ć. Szczegółowe informacje znajdziesz w sekcji Zarezerwowane nazwy.
Zarezerwowane nazwy
Measurement Protocol ma kilka zastrzeżonych 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:
screen_view: to zdarzenie jest dozwolone tylko w przypadku strumieni danych z aplikacji. W przypadku strumieni danych z sieci użyj parametrupage_view.ad_impression: to zdarzenie jest dozwolone tylko w przypadku strumieni danych z aplikacji.in_app_purchase: to zdarzenie jest dozwolone tylko w przypadku strumieni danych z aplikacji. W przypadku strumieni danych z sieci używaj zdarzeniapurchase.
Dodatkowe wymagania dotyczące poszczególnych przypadków użycia znajdziesz w sekcji Typowe przypadki użycia.