Odniesienie do platformy Measurement Protocol

Na tej stronie opisujemy mechanizm transportu i parametry danych w Measurement Protocol.

Transport

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

Wyślij żądania do tego punktu końcowego:

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

Jeśli chcesz, aby Twoje 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 ładunkiem żądania.

Jeśli żądanie HTTP zostanie odebrane, Measurement Protocol zwraca kod stanu 2xx. Measurement Protocol nie zwraca kodu błędu, jeśli ładunek jest nieprawidłowo sformatowany, dane są nieprawidłowe lub nie zostały przetworzone przez Google Analytics.

Ładunek

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

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

Parametry zapytania

Nazwa parametru Opis

api_secret

 Wymagany. Tajny klucz API z interfejsu Google Analytics.

Znajdziesz go w sekcji Administracja > Strumienie danych > Wybierz strumień > Measurement Protocol > Utwórz.

prywatne dla Twojej organizacji, Powinny być regularnie aktualizowane, aby uniknąć nadmiernej ilości spamu.

firebase_app_id

 Wymagany. Identyfikator aplikacji w Firebase. Identyfikator aplikacji w Firebase.

Znajdziesz go w konsoli Firebase w sekcji Ustawienia projektu > Ogólne > Twoje aplikacje > Identyfikator aplikacji.

Treść żądania POST w formacie JSON

Rozmiar treści POST JSON musi być mniejszy niż 130 kB.

Klucz Typ Opis

app_instance_id

 string Wymagany. Unikalny identyfikator konkretnej instalacji aplikacji w Firebase.

Nie jest to to samo co client_id internetowa.

Należy pobrać za pomocą pakietu SDK Firebase:

user_id

 string

Opcjonalnie. unikalny identyfikator użytkownika. Więcej informacji o tym identyfikatorze znajdziesz w artykule Funkcja User-ID do analizy na wielu platformach. Może zawierać tylko znaki w kodowaniu UTF-8.

timestamp_micros

 number

Opcjonalnie. Sygnatura czasowa systemu Unix, mikrosekundy, a nie milisekundy. Reprezentuje czas zdarzenia. Należy ją ustawić tylko w celu rejestrowania zdarzeń, które miały miejsce w przeszłości. Można je zastąpić za pomocą user_property lub sygnatur czasowych zdarzeń. Zdarzenia mogą być datowane wstecznie do 72 godzin.

user_properties

 object Opcjonalnie. Właściwości użytkownika na potrzeby pomiaru. W każdym żądaniu można wysłać maksymalnie 25 właściwości użytkownika. Nazwa właściwości użytkownika może mieć maksymalnie 24 znaki, a jej wartość – 36 znaków.

user_data

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

non_personalized_ads

 boolean Opcjonalny. Ustaw wartość true, aby wskazać, że dane użytkownika nie powinny być używane do wyświetlania reklam spersonalizowanych.

user_location

 object Opcjonalnie. Ustawia informacje geograficzne dla żądania w uporządkowanym formacie.

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 dla żądania w uporządkowanym formacie.

validation_behavior

 string

Opcjonalnie: Ustawia zachowanie weryfikacji żądania.

Może to być RELAXED lub ENFORCE_RECOMMENDATIONS. Jeśli nie zostanie podany, domyślnie przyjmuje się RELAXED.

events[]

 array Wymagany. Tablica elementów event. W jednym żądaniu można wysłać maksymalnie 25 zdarzeń. Informacje o zalecanych zdarzeniach znajdziesz w materiałach dotyczących zdarzeń.

events[].name

 string Wymagany. Nazwa zdarzenia. Nazwy zdarzeń mogą mieć maksymalnie 40 znaków. Zalecane zdarzenia znajdziesz w sekcji Zdarzenia.

events[].params

 object Opcjonalnie. Parametry zdarzenia. Z każdym zdarzeniem można wysłać maksymalnie 25 parametrów. Więcej informacji o zalecanych parametrach poszczególnych zdarzeń znajdziesz w artykule Zdarzenia, a o często używanych parametrach zdarzeń – w artykule Często używane parametry zdarzeń.

Nazwy parametrów mogą mieć maksymalnie 40 znaków. Wartości parametró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.

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 być zgodny z wyrażeniem regularnym ^\d+$.

Należy pobrać za pomocą pakietu SDK Firebase:

engagement_time_msec

 number Czas trwania zaangażowania użytkowników 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. Użyj tego parametru, aby zastąpić sygnaturę czasową zdarzenia.

Atrybut consent konfiguruje typy i stany zgody. Jeśli nie podasz parametru consent, Google Analytics użyje ustawień zgody z odpowiednich interakcji online dla klienta lub instancji aplikacji.

Klucz Typ Opis

ad_user_data

 string

Opcjonalnie. Zgoda na wysyłanie do Google danych użytkownika ze zdarzeń i właściwości użytkownika z żądania w celach reklamowych.

Może to być GRANTED lub DENIED.

ad_personalization

 string

Opcjonalnie. Zgoda użytkownika na reklamy spersonalizowane.

Może to być GRANTED lub DENIED.

Informacje geograficzne

Atrybuty user_location i ip_override dostarczają informacji geograficznych. user_location ma pierwszeństwo przed zasadą 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ż parametry country_id i region_id, aby usługa Google Analytics mogła prawidłowo zmapować nazwę miasta na identyfikator miasta.

region_id

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

country_id

 string Opcjonalnie. Kraj w formacie ISO 3166-1 alfa-2. Na przykład: 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ładowy plik 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 będzie uzyskiwać informacje geograficzne z adresu IP. Jeśli wysyłasz user_location, Google Analytics ignoruje ip_override.

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

Google Analytics stosuje do żądania ustawienia szczegółowych danych o lokalizacji usługi niezależnie od wysł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 platformę, 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ładowe ustawienia 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"
}
Jeśli żądanie nie określa parametru device, Google Analytics uzyskuje informacje o urządzeniu ze zdarzeń tagowania za pomocą parametru app_instance_id.

Niezależnie od tego, czy podaszdevice,Google Analytics zastosuje do żądania ustawienia szczegółowych danych o urządzeniu obowiązujące w usłudze.

Sposób weryfikacji

Atrybut validation_behavior określa, jak Measurement Protocol sprawdza zawartość żądania.

  • Weryfikacja RELAXED odrzuca tylko nieprawidłowo sformułowane żądania. Może nadal akceptować zdarzenia i parametry z nieprawidłowymi nazwami pól lub z danymi, które nie są prawidłowego typu, ale ignoruje parametry, które przekraczają limity. Measurement Protocol domyślnie używa walidacji RELAXED.
  • Weryfikacja ENFORCE_RECOMMENDATIONS odrzuca parametry zdarzeń i produktów, które nie są prawidłowego 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 przypada w ciągu ostatnich 72 godzin.

Zalecamy wykonanie tych czynności:

  • Podczas sprawdzania poprawności zdarzeń używaj parametru ENFORCE_RECOMMENDATIONS, aby uzyskać jak najwięcej informacji o potencjalnych problemach z żądaniami.

    Żądania możesz też sprawdzać za pomocą Kreatora zdarzeń, ponieważ podczas sprawdzania żądań określa on parametr ENFORCE_RECOMMENDATIONS.

  • Aby zminimalizować ilość danych odrzucanych przez Measurement Protocol, nie podawaj parametru validation_behavior podczas wysyłania zdarzeń.

    Jeśli podczas wysyłania konkretnego żądania chcesz nadać priorytet ścisłej weryfikacji, a nie zbieraniu danych, dodaj pole validation_behavior i ustaw je na ENFORCE_RECOMMENDATIONS.

Parametry niestandardowe

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

  • Parametry niestandardowe ograniczone do użytkownika mogą być uwzględniane w user_properties.
  • Parametry niestandardowe ograniczone do zdarzenia mogą być uwzględniane 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 artykule 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ą się zaczynać od:

  • _ (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_