Odniesienie do platformy Measurement Protocol

Na tej stronie opisujemy mechanizm przesyłania i parametry danych w protokole pomiarowym.

Transport

Wszystkie dane muszą być wysyłane bezpiecznie za pomocą żądań HTTPSPOST.

Wysyłaj żądania do tego punktu końcowego:

https://www.google-analytics.com/mp/collect

Jeśli chcesz, aby dane były zbierane w UE, użyj tego punktu końcowego:

https://region1.google-analytics.com/mp/collect

Oto przykładowe żądanie POST:

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

Zastąp PAYLOAD_DATA elementem Payload żądania.

Jeśli żądanie HTTP zostanie odebrane, Measurement Protocol zwróci kod stanu 2xx. Measurement Protocol nie zwraca kodu błędu, jeśli ładunek jest zniekształcony lub jeśli dane są nieprawidłowe albo nie są przetwarzane przez Google Analytics.

Ładunek

Ładunek składa się z 2 części:

  1. Parametry zapytania.
  2. Treść w formacie JSON POST.

Parametry zapytania

Nazwa parametru Opis

api_secret

 Wymagany. Tajny klucz API z interfejsu Google Analytics.

Znajduje się w sekcji Administracja > Strumienie danych > Wybierz swój strumień > Measurement Protocol > Utwórz.

prywatne dla Twojej organizacji. Powinna być regularnie aktualizowana, aby uniknąć nadmiernego spamu.

Treść żądania POST w formacie JSON

Klucz Typ Opis

user_id

 string

Opcjonalnie. unikalny identyfikator użytkownika. Więcej informacji o tym identyfikatorze znajdziesz w artykule Używanie funkcji User-ID do analizy obejmującej wiele platform. Może zawierać tylko znaki UTF-8.

timestamp_micros

 number

Opcjonalnie. Sygnatura czasowa w formacie czasu uniksowego w mikrosekundach, a nie w milisekundach. Reprezentuje czas zdarzenia. Należy ustawić tylko w przypadku rejestrowania zdarzeń, które miały miejsce w przeszłości. Może zostać zastąpiony przez user_property lub sygnatury czasowe zdarzeń. Zdarzenia można datować wstecznie maksymalnie o 72 godziny.

user_properties

 object Opcjonalnie. Właściwości użytkownika dla pomiaru.

user_data

 object Opcjonalnie. Dane przekazywane przez użytkowników.
object Opcjonalnie. Ustawienia zgody w przypadku żądania. Więcej informacji znajdziesz w sekcji dotyczącej zgody.

non_personalized_ads

 boolean Opcjonalny Ustaw wartość true, aby wskazać, że danych użytkownika nie należy używać do wyświetlania reklam spersonalizowanych.

user_location

 object Opcjonalnie. Ustawia informacje geograficzne w żądaniu w formacie strukturalnym.

ip_override

 string Opcjonalnie. Adres IP, którego Google Analytics używa do uzyskiwania informacji geograficznych na potrzeby żądania.

device

 object Opcjonalnie: Ustawia informacje o urządzeniu w żądaniu w formacie uporządkowanym.

validation_behavior

 string

Opcjonalnie: Ustawia zachowanie weryfikacji w przypadku żądania.

Może to być RELAXED lub ENFORCE_RECOMMENDATIONS. Jeśli nie zostanie podana, domyślnie przyjmuje wartość RELAXED.

events[]

 array Wymagany. Tablica event elementów. W jednym żądaniu można wysłać maksymalnie 25 zdarzeń. Wszystkie prawidłowe zdarzenia znajdziesz w dokumentacji zdarzeń.

events[].name

 string Wymagany. Nazwa zdarzenia. Wszystkie opcje znajdziesz w sekcji Zdarzenia.

events[].params

 object Opcjonalnie. Parametry zdarzenia. Sugerowane parametry poszczególnych zdarzeń znajdziesz w sekcji Zdarzenia, a parametry zdarzeń wspólnych.

Typowe parametry zdarzenia

Measurement Protocol ma te wspólne parametry zdarzeń:

Klucz Typ Opis

session_id

 number Liczba dodatnia, która identyfikuje sesję użytkownika. Wymagane w przypadku kilku typowych zastosowań. Musi pasować do wyrażenia regularnego ^\d+$.

engagement_time_msec

 number Czas trwania zaangażowania użytkownika w milisekundach w przypadku zdarzenia. Użyj wartości, która odzwierciedla czas zaangażowania użytkownika od poprzedniego zdarzenia.

timestamp_micros

 number czas od początku epoki uniksowej podawany w mikrosekundach w przypadku zdarzenia. Za pomocą tego parametru możesz zastąpić sygnaturę czasową zdarzenia.

Atrybut consent konfiguruje typy i stany zgody. Jeśli nie określisz wartości parametru consent, Google Analytics użyje ustawień zgody z odpowiednich interakcji online w przypadku klienta lub instancji aplikacji.

Klucz Typ Opis

ad_user_data

 string

Opcjonalnie. Stan zgody na wysyłanie do Google danych użytkownika z wydarzeń i właściwości użytkownika w żądaniu w celach reklamowych.

Może to być GRANTED lub DENIED.

ad_personalization

 string

Opcjonalnie. Stan zgody użytkownika na reklamy spersonalizowane.

Może to być GRANTED lub DENIED.

Informacje geograficzne

Atrybuty user_location i ip_override zawierają informacje geograficzne. user_location ma pierwszeństwo przed ip_override.

Oto struktura pola user_location. Podaj jak najwięcej atrybutów. Zalecamy co najmniej country_id i region_id.

Klucz Typ Opis

city

 string Opcjonalnie. Nazwa miasta. Jeśli miasto znajduje się w Stanach Zjednoczonych, ustaw też country_id i region_id, aby Google Analytics mógł prawidłowo mapować nazwę miasta na identyfikator miasta.

region_id

 string Opcjonalnie. Kraj i podział podrzędny w formacie ISO 3166. Przykłady: US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

 string Opcjonalnie. Kraj w formacie ISO 3166-1 alfa-2. Przykłady: US, AU, ES, FR.

subcontinent_id

 string Opcjonalnie. Subkontynent w formacie UN M49. Na przykład: 011, 021, 030, 039.

continent_id

 string Opcjonalnie. Kontynent w formacie UN M49. Na przykład: 002, 019, 142, 150.

Oto przykład user_location:

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override to alternatywa dla user_location. Jeśli zamiast tego wyślesz ip_override, Google Analytics wygeneruje informacje geograficzne na podstawie adresu IP. Jeśli wyślesz user_location, Google Analytics zignoruje ip_override.

Jeśli nie wysyłasz parametrów user_location ani ip_override, Google Analytics uzyskuje informacje geograficzne ze zdarzeń tagowania za pomocą parametrów client_id.

Google Analytics stosuje do żądania ustawienia szczegółowych danych o lokalizacji usługi, niezależnie od wysyłanych informacji geograficznych.

Informacje o urządzeniu

Aby wysłać informacje o urządzeniu, użyj pola device. Oto struktura pola device. Podaj jak najwięcej atrybutów. Zalecamy co najmniej category.

Klucz Typ Opis

category

 string Opcjonalnie. Kategoria urządzenia. Na przykład: desktop, tablet, mobile, smart TV.

language

 string Opcjonalnie. Język w formacie ISO 639-1. Na przykład: en, en-US.

screen_resolution

 string Opcjonalnie. Rozdzielczość urządzenia w formacie WIDTHxHEIGHT. Na przykład: 1280x2856, 1080x2340.

operating_system

 string Opcjonalnie. System operacyjny lub platforma. Na przykład: MacOS.

operating_system_version

 string Opcjonalnie. Wersja systemu operacyjnego lub platformy. Na przykład: 13.5.

model

 string Opcjonalnie. Model urządzenia. Na przykład: Pixel 9 Pro, Samsung Galaxy S24.

brand

 string Opcjonalnie. Marka urządzenia. Na przykład: Google, Samsung.

browser

 string Opcjonalnie. Marka lub typ przeglądarki. Na przykład: Chrome, Firefox.

browser_version

 string Opcjonalnie. Wersja przeglądarki. Na przykład: 136.0.7103.60, 5.0.

Poniższy fragment kodu pokazuje przykład ustawień device:

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

Niezależnie od tego, czy określisz Google Analytics zastosuje do żądania ustawienia usługi dotyczące szczegółowych danych o urządzeniach.

Sposób weryfikacji

Atrybut validation_behavior określa, w jaki sposób Measurement Protocol weryfikuje zawartość żądania.

  • Weryfikacja RELAXED odrzuca tylko nieprawidłowo sformułowane żądania. Może on nadal akceptować zdarzenia i parametry z nieprawidłowymi nazwami pól lub danymi, które nie są odpowiedniego typu, ale ignoruje parametry przekraczające limity. Platforma Measurement Protocol domyślnie korzysta z RELAXED weryfikacji.
  • ENFORCE_RECOMMENDATIONS weryfikacja odrzuca parametry zdarzeń i produktów, które nie są odpowiedniego typu lub zawierają parametry przekraczające limity. Dodatkowo ENFORCE_RECOMMENDATIONS odrzuca każde zdarzenie lub właściwość użytkownika z sygnaturą czasową, która nie mieści się w zakresie ostatnich 72 godzin.

Zalecamy wykonanie tych czynności:

  • Używaj parametru ENFORCE_RECOMMENDATIONS podczas weryfikowania zdarzeń, aby uzyskać jak najwięcej informacji zwrotnych o potencjalnych problemach z Twoimi żądaniami.

    Żądania możesz też weryfikować za pomocą Kreatora zdarzeń, ponieważ określa on ENFORCE_RECOMMENDATIONS, kiedy należy to robić.

  • Nie podawaj parametru validation_behavior, gdy wysyłasz zdarzenia, aby zminimalizować ilość danych odrzucanych przez Measurement Protocol.

    Jeśli podczas wysyłania konkretnego żądania chcesz nadać priorytet ścisłej weryfikacji nad zbieraniem danych, dodaj pole validation_behavior i ustaw jego wartość na ENFORCE_RECOMMENDATIONS.

Parametry niestandardowe

W ładunku Measurement Protocol możesz uwzględniać niestandardowe parametry ograniczone do użytkownika, zdarzenia i produktu.

  • Parametry niestandardowe ograniczone do użytkownika można uwzględnić w user_properties.
  • Parametry niestandardowe ograniczone do zdarzenia można uwzględnić w events[].params.
  • Parametry niestandardowe ograniczone do produktu mogą być uwzględniane w items.

Niektóre zdarzenia mają zalecane parametry. Zalecane parametry wszystkich obsługiwanych zdarzeń znajdziesz w sekcji zdarzenia.

Zarezerwowane nazwy

Niektóre nazwy zdarzeń, parametrów i właściwości użytkownika są zarezerwowane i nie można ich używać:

Zarezerwowane nazwy zdarzeń

Te nazwy zdarzeń są zarezerwowane i nie można ich używać:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

Dodatkowo zdarzenia ad_impression, in_app_purchase i screen_view są dozwolone tylko w przypadku strumieni danych z aplikacji.

Zastrzeżone nazwy parametrów

Te nazwy parametrów są zarezerwowane i nie można ich używać:

  • firebase_conversion

Nazwy parametrów nie mogą zaczynać się od tych znaków:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

Zarezerwowane nazwy właściwości użytkownika

Te nazwy właściwości użytkownika są zarezerwowane i nie można ich używać:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

Oprócz tego nazwy właściwości użytkownika nie mogą się zaczynać od:

  • _ (underscore)
  • firebase_
  • ga_
  • google_