Odniesienie do platformy Measurement Protocol

Z tego artykułu dowiesz się, jak wysyłać dane do Google Analytics za pomocą Measurement Protocol.

Przegląd

Wysyłanie danych do Google Analytics za pomocą Measurement Protocol składa się z 2 części:

• Transport – dokąd i w jaki sposób wysyłasz dane
• Ładunek, czyli dane, które wysyłasz

W tym dokumencie opisano sposób formatowania obu formatów.

Transport

Punkt końcowy adresu URL

Wysyłasz dane za pomocą Measurement Protocol, wysyłając żądania HTTP do tego punktu końcowego:

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

Wszystkie dane powinny być przesyłane w bezpieczny sposób za pomocą protokołu HTTPS.

Dane możesz wysyłać za pomocą żądań POST lub GET.

Użycie metody POST

Zalecamy wysyłanie danych metodą POST, ponieważ umożliwia to utworzenie większego ładunku. Korzystając z metody POST, wyślij to żądanie HTTP:

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

Gdzie:

• user_agent_string – to sformatowany ciąg znaków klienta użytkownika służący do obliczania tych wymiarów: przeglądarka, platforma i możliwości urządzeń mobilnych.

  Jeśli ta wartość nie zostanie ustawiona, powyższe dane nie zostaną obliczone.

• payload_data – BODY żądania publikacji. Treść musi zawierać dokładnie 1 ładunek zakodowany za pomocą identyfikatora URI, a jego długość nie może być większa niż 8192 bajty.
• Adres IP – jest domyślnie wysyłany w żądaniu HTTP i służy do obliczania wszystkich wymiarów geograficznych / sieci w Google Analytics.

GET

W środowiskach, w których nie można wysyłać danych POST, możesz też wysyłać żądania HTTP GET do tego samego punktu końcowego:

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

Miejsce, do którego są wysyłane dane ładunku jako parametry zapytania ze zmianą znaczenia dla identyfikatora URI. Długość całego zakodowanego adresu URL nie może przekraczać 8000 bajtów.

Pomijanie pamięci podręcznej

W niektórych środowiskach, np. w przeglądarkach, żądania HTTP GET mogą być przechowywane w pamięci podręcznej. Gdy żądania są zapisywane w pamięci podręcznej, kolejne żądania mogą być pobierane z pamięci podręcznej i nie wysyłane do Google Analytics. Aby pominąć pamięć podręczną, protokół Measurement Protocol udostępnia specjalny parametr (z), który można ustawić jako liczbę losową. Dzięki temu wszystkie żądania Measurement Protocol będą niepowtarzalne, a kolejne żądania nie będą pobierane z pamięci podręcznej.

Jeśli używasz pomijania pamięci podręcznej, zdecydowanie zalecamy dodanie tego parametru jako ostatniego parametru w ładunku.

https://www.google-analytics.com/collect?payload_data&z=123456

Kody odpowiedzi

Measurement Protocol zwróci kod stanu 2xx po otrzymaniu żądania HTTP. Measurement Protocol nie zwraca kodu błędu, jeśli dane ładunku mają nieprawidłowy format, są nieprawidłowe lub nie zostały przetworzone przez Google Analytics.

Jeśli nie otrzymasz kodu stanu 2xx, NIE ponawiaj żądania. Zamiast tego zatrzymaj i popraw wszystkie błędy w żądaniu HTTP.

Dane ładunku

Wszystkie dane zbierane przez Google Analytics za pomocą platformy Measurement Protocol są wysyłane jako ładunek. Ładunek przypomina ciąg zapytania URL, w którym każdy parametr ma klucz i wartość, jest rozdzielony znakiem =, a każda para jest oddzielona znakiem &. Na przykład:

key1=val1&key2=val2

Każdy ładunek ma reguły regulujące: wymagane wartości, kodowanie URI, parametry, które można wysyłać razem, oraz długość parametrów. Poza tym każdy parametr ma określony typ, który wymaga określonego formatu. Omówione reguły zostały opisane w sekcjach poniżej.

Pełną listę wszystkich parametrów, które możesz wysyłać za pomocą Measurement Protocol, znajdziesz w dokumentacji parametrów.

Wymagane wartości dla wszystkich działań

W każdym ładunku muszą się znajdować te parametry:

Nazwa	Parametr	Przykład	Opis
Wersja protokołu	v	v=1	Wersja protokołu. Wartość powinna wynosić 1.
Identyfikator śledzenia	tid	tid=UA-123456-1	Identyfikator odróżniający, do której usługi w Google Analytics mają być wysyłane dane.
Identyfikator klienta	cid	cid=xxxxx	Unikalny identyfikator konkretnego użytkownika.
Typ działania	t	t=pageview	Rodzaj interakcji zebranej dla określonego użytkownika.

Dane Client ID i Hit Type to wartości mapowane bezpośrednio na model danych Google Analytics. Jeśli chcesz śledzić użytkownika 5555, który odwiedził /pageA, /pageB i /pageC, musisz wysłać te 3 ładunki:

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

Zwróć uwagę, że pole / jest zakodowane jako %2F.

Wartości kodowania adresów URL

Wszystkie wartości wysyłane do Google Analytics muszą być zarówno zakodowane za pomocą adresu URL, jak i UTF-8. Aby wysłać klucz dp z wartością /my page €, musisz najpierw sprawdzić, czy jest on zakodowany w formacie UTF-8, a następnie adres URL. Efektem jest końcowy ciąg znaków:

dp=%2Fmy%20page%20%E2%82%AC

Jeśli którykolwiek ze znaków zostanie zakodowany nieprawidłowo, zostanie zastąpiony znakiem zastępczym Unicode xFFFD.

Wymagane wartości dla niektórych typów działań

Niektóre parametry można wysyłać tylko w przypadku określonych rodzajów działań. Na przykład typ działania pageview wymaga ustawienia parametru Ścieżka do strony (dp). W dokumentacji parametrów znajdziesz informacje o tym, jakie parametry są wymagane w przypadku poszczególnych typów działań.

Maksymalna długość

Niektóre wartości tekstowe w Measurement Protocol mają określoną maksymalną długość w bajtach. Na przykład pole dr strony odsyłającej do dokumentu ma maksymalną długość 2048 bajtów. Jeśli któraś z wartości przekracza maksymalną długość, zostanie automatycznie obcięta. Jeśli znak wielobajtowy przekracza maksymalną długość, cały znak zostanie obcięty.

Obsługiwane typy danych

Każde pole danych w protokole Measurement Protocol należy do określonego typu, a każde z nich ma własne reguły weryfikacji. Jeśli któraś z wartości parametru nie będzie zgodna z regułami weryfikacji, Google Analytics zignoruje ten parametr i nie przetworzy go. Pozostałe parametry będą przetwarzane w zwykły sposób.

Uwaga: jeśli wymagany parametr ma nieprawidłowy format, cały ładunek nie zostanie przetworzony. Na przykład wysłanie wartości bogus dla wymaganego parametru typu działania sprawi, że cały ładunek nie zostanie przetworzony.

Measurement Protocol obsługuje te typy danych:

• Tekst
• Currency (Waluta)
• Wartość logiczna
• Liczba całkowita
• Number

Pamiętaj, że poszczególne pola danych mogą mieć własne ograniczenia. Pełną listę wszystkich pól danych i akceptowanych typów znajdziesz w dokumentacji pól.

Tekst

Służy do reprezentowania ciągów tekstowych. W przypadku pól tekstowych wykonywane są dodatkowe przetwarzanie. Wszystkie początkowe i końcowe znaki odstępu zostaną usunięte. Wewnętrzne wyświetlanie co najmniej 2 znaków odstępów (w tym spacji, tabulatorów, nowych wierszy itp.) jest ograniczone do jednego znaku spacji. To przekształcenie jest stosowane do nieprzetworzonego tekstu, zanim dojdzie do obcięcia. Na przykład:

   Hello      World

zmienią się w:

Hello World

Waluta

Służy do reprezentowania łącznej wartości waluty. Separator dziesiętny oddziela całą walutę od ułamkowej części waluty. z dokładnością do sześciu miejsc po przecinku. W przypadku pola waluty obowiązują te wartości:

1000.000001

Po przesłaniu wartości do Google Analytics cały tekst jest usuwany aż do pierwszej cyfry, znaku - lub znaku dziesiętnego .. Przykłady:

$-55.00

zmienią się w:

-55.00

Wartość logiczna

Służy do określania, czy wartość jest ustawiona na „prawda” czy „fałsz”. Prawidłowe wartości to:

• 1 – Prawda
• 0 – fałsz

Liczba całkowita

Służy do reprezentowania liczby całkowitej. Wartość jest przechowywana jako int64 ze znakiem

Liczby

Służy do reprezentowania liczby całkowitej lub liczby zmiennoprzecinkowej.