W tym dokumencie opisujemy kilka zaawansowanych funkcji interfejsu Google Analytics Data API w wersji 1. Szczegółowy opis interfejsu API znajdziesz w jego dokumentacji.
Wyświetlanie listy definicji niestandardowych i tworzenie raportów
Interfejs Data API może tworzyć raporty o zarejestrowanych niestandardowych wymiarach i danych niestandardowych. Method API API może służyć do wyświetlania nazw interfejsów API zarejestrowanych w Twojej usłudze niestandardowych definicji niestandardowych. Tych nazw interfejsów API można używać np. w żądaniach raportów wysyłanych do metody runReport.
W kolejnych sekcjach znajdziesz przykłady poszczególnych typów definicji niestandardowej. W tych przykładach zastąp GA4_PROPERTY_ID
swoim identyfikatorem usługi.
Wymiary niestandardowe ograniczone do zdarzenia
Krok 1. Wyślij zapytanie do metody metadanych API, podając identyfikator usługi.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Krok 2. Znajdź wymiar niestandardowy ograniczony do zdarzenia, na podstawie którego chcesz tworzyć raporty z odpowiedzi. Jeśli wymiar nie jest dostępny, musisz go zarejestrować.
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
Krok 3. Uwzględnij wymiar niestandardowy w żądaniu raportu. Poniżej znajdziesz przykładowe żądanie metody runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [{ "name": "customEvent:achievement_id" }],
"metrics": [{ "name": "eventCount" }]
}
Wymiary niestandardowe ograniczone do użytkownika
Krok 1. Wyślij zapytanie do metody metadanych API, podając identyfikator usługi.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Krok 2. Znajdź wymiar niestandardowy o zakresie na poziomie użytkownika, na podstawie którego chcesz utworzyć raporty z odpowiedzi. Jeśli wymiar nie jest dostępny, musisz go zarejestrować.
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
Krok 3. Uwzględnij wymiar niestandardowy w żądaniu raportu. Poniżej znajdziesz przykładowe żądanie metody runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"entity": { "propertyId": "GA4_PROPERTY_ID" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "customUser:last_level" }],
"metrics": [{ "name": "activeUsers" }]
}
Dane niestandardowe ograniczone do zdarzenia
Krok 1. Wyślij zapytanie do metody metadanych API, podając identyfikator usługi.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Krok 2. Znajdź dane niestandardowe ograniczone do zdarzenia, na podstawie których chcesz tworzyć raporty z odpowiedzi. Jeśli dane są niedostępne, musisz je zarejestrować.
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Krok 3. Uwzględnij w żądaniu raportu dane niestandardowe. Poniżej znajdziesz przykładowe żądanie metody runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "customEvent:credits_spent" }]
}
Dane dotyczące współczynnika kluczowych zdarzeń w przypadku jednego zdarzenia
Krok 1. Wyślij zapytanie do metody metadanych API z użyciem identyfikatora usługi.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Krok 2. Znajdź dane współczynnika kluczowych zdarzeń dla jednego kluczowego zdarzenia, o którym chcesz tworzyć raporty na podstawie odpowiedzi. Jeśli nie ma kluczowego zdarzenia, musisz skonfigurować je.
"metrics": [
...
{
"apiName": "sessionKeyEventRate:add_to_cart",
"uiName": "Session key event rate for add_to_cart",
"description": "The percentage of sessions in which a specific key event was triggered",
},
...
],
Krok 3. Uwzględnij w żądaniu raportu dane dotyczące współczynnika kluczowych zdarzeń. Poniżej znajdziesz przykładowe żądanie wysyłane do metody runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}
Średnie dane niestandardowe ograniczone do zdarzenia
Krok 1. Wyślij zapytanie do metody metadanych API, podając identyfikator usługi.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Krok 2. Znajdź średnią danych niestandardowych ograniczonych do zdarzenia, na podstawie której chcesz tworzyć raporty z odpowiedzi. Jeśli dane są niedostępne, musisz je zarejestrować.
"metrics": [
...
{
"apiName": "averageCustomEvent:credits_spent",
"uiName": "Average Credits Spent",
"description": "The average of an event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Krok 3. Uwzględnij w żądaniu raportu średnią z danych niestandardowych. Poniżej znajdziesz przykładowe żądanie metody runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}
Przykłady raportów dotyczących kohorty
Raporty dotyczące kohorty tworzą serię czasową utrzymania użytkowników w danej kohorcie. Szczegółową dokumentację poszczególnych pól interfejsu API znajdziesz w dokumentacji REST CohortSpec.
Tworzenie raportu dotyczącego kohorty
Oto przykładowy raport dotyczący kohorty, w którym:
- Kohorta to użytkownicy z
firstSessionDate
o wartości2020-12-01
. Jest ona konfigurowana przez obiektcohorts
. Wymiary i dane w odpowiedzi na raport będą oparte tylko na użytkownikach kohorty. - Raport dotyczący kohorty będzie zawierał 3 kolumny. Są one konfigurowane za pomocą obiektów wymiarów i danych.
- Wymiar
cohort
to nazwa kohorty. - Wymiar
cohortNthDay
to liczba dni od2020-12-01
. - Dane
cohortActiveUsers
to liczba wciąż aktywnych użytkowników.
- Wymiar
- Obiekt
cohortsRange
określa, że raport powinien zawierać dane zdarzeń dla tej kohorty od2020-12-01
do2020-12-06
.- Jeśli używana jest szczegółowość
DAILY
, zalecany jest wymiarcohortNthDay
, który zapewnia spójność.
- Jeśli używana jest szczegółowość
Żądanie raportu dla kohorty to:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
"metrics": [{ "name": "cohortActiveUsers" }],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "DAILY"
}
},
}
Przykładowa odpowiedź na to żądanie to:
{
"dimensionHeaders": [
{ "name": "cohort" }, { "name": "cohortNthDay" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "293" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "143" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "123" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "92" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
"metricValues": [{ "value": "86" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "83" }]
}
],
"metadata": {},
"rowCount": 6
}
Na podstawie tej odpowiedzi do raportu widoczny jest wykres dotyczący raportu dotyczącego kohorty. Z tego raportu wynika, że największy spadek liczby aktywnych użytkowników w tej kohorcie nastąpił między pierwszym a drugim dniem.
Wiele kohort i odsetek utrzymania użytkowników
Pozyskiwanie i utrzymywanie użytkowników to sposoby na rozwój witryny lub aplikacji. Raporty dotyczące kohorty koncentrują się na utrzymaniu użytkowników. W tym przykładzie raport pokazuje, że w ciągu 2 tygodni ta usługa poprawiła wskaźnik utrzymania użytkowników w ciągu 4 dni o 10%.
Aby utworzyć ten raport, określamy 3 kohorty: pierwsza z firstSessionDate
o wartości 2020-11-02
, druga z firstSessionDate
o wartości 2020-11-09
oraz trzecia z firstSessionDate
o wartości 2020-11-16
. Liczba użytkowników Twojej usługi w tych 3 dniach będzie inna, dlatego porównujemy dane dotyczące utrzymania użytkowników w kohorcie cohortActiveUsers/cohortTotalUsers
, zamiast korzystać z danych Bezpośrednie cohortActiveUsers
.
Żądanie raportu dotyczące tych kohort:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metrics": [
{
"name": "cohortRetentionFraction",
"expression": "cohortActiveUsers/cohortTotalUsers"
}
],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
}
],
"cohortsRange": {
"endOffset": 4,
"granularity": "DAILY"
}
},
}
Przykładowa odpowiedź na to żądanie to:
{
"dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metricHeaders": [{
"name": "cohortRetentionFraction",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
"metricValues": [{ "value": "0.308" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
"metricValues": [{ "value": "0.272" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
"metricValues": [{ "value": "0.257" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "0.248" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
"metricValues": [{ "value": "0.235" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
"metricValues": [{ "value": "0.211" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
"metricValues": [{ "value": "0.198" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "0.172" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
"metricValues": [{ "value": "0.167" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
"metricValues": [{ "value": "0.155" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "0.141" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "0.118" }]
}
],
"metadata": {},
"rowCount": 15
}
Na podstawie tej odpowiedzi do raportu widoczny jest wykres dotyczący raportu dotyczącego kohorty. Z tego raportu wynika, że w ciągu 2 tygodni 4-dniowy wskaźnik utrzymania użytkowników wzrósł o 10%. Późniejsza kohorta z firstSessionDate
z 2020-11-16
przekracza utrzymanie uwagi odbiorców z wcześniejszej kohorty (firstSessionDate
z 2020-11-02
).
Kohorty tygodniowe i korzystanie z kohort z innymi funkcjami interfejsu API
Aby usunąć codzienną wariancję w zachowaniu użytkowników, użyj kohort tygodniowych. W tygodniowych raportach dotyczących kohorty wszyscy użytkownicy z danymi firstSessionDate
w tym samym tygodniu tworzą kohortę. Tydzień zaczyna się w niedzielę, a kończy w sobotę. Ponadto w tym raporcie dzielimy tę kohortę, aby porównać użytkowników z aktywnością w Rosji z użytkownikami aktywnymi w Meksyku. W tym wycinku użyto wymiaru country
i elementu dimensionFilter
, aby uwzględnić tylko 2 kraje.
Żądanie raportu dotyczące tych kohort:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dimensions": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metrics": [{ "name": "cohortActiveUsers" }],
"dimensionFilter": {
"filter": {
"fieldName": "country",
"inListFilter": {
"values": [ "Russia", "Mexico" ]
}
}
},
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": {
"startDate": "2020-10-04",
"endDate": "2020-10-10"
}
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "WEEKLY"
}
},
}
Przykładowa odpowiedź na to żądanie to:
{
"dimensionHeaders": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
],
"metricValues": [{ "value": "105" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "98" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "35" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "24" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
],
"metricValues": [{ "value": "23" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "17" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
],
"metricValues": [{ "value": "3" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
}
],
"metadata": {},
"rowCount": 11
}
Na podstawie tej odpowiedzi do raportu widoczny jest wykres raportu dotyczącego kohorty. Z tego raportu wynika, że ta usługa skuteczniej zatrzymuje użytkowników aktywnych w Meksyku niż ci z Rosji.
Porównania
Dzięki porównaniom możesz analizować równolegle podzbiory danych. Aby definiować porównania, podaj w definicji raportu pole comparisons
. Funkcja „Porównanie” w interfejsie Data API jest podobna do porównań w interfejsie Google Analytics.
Szczegółową dokumentację każdego pola interfejsu API znajdziesz w dokumentacji REST (w języku angielskim).
Utwórz porównanie
Możesz utworzyć osobne porównanie dla każdego zbioru danych, który chcesz porównać. Aby np. porównać dane z witryny i aplikacji, możesz utworzyć jedno porównanie danych z Androida i iOS oraz drugie dla danych z internetu.
Oto przykładowy raport, który definiuje 2 porównania i zwraca aktywnych użytkowników z podziałem na kraje.
Pierwsze porównanie o nazwie „Ruch w aplikacji” korzysta z parametru inListFilter
, aby dopasować wymiar platform
do wartości „iOS” i „Android”. W drugim porównaniu o nazwie „Ruch w witrynie” użyto parametru stringFilter
, aby dopasować wymiar platform
do słowa „sieć”.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"comparisons": [
{
"name": "App traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"inListFilter": {
"values": [
"iOS",
"Android"
]
}
}
}
},
{
"name": "Web traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"stringFilter": {
"matchType": "EXACT",
"value": "web"
}
}
}
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
],
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
]
}
W przypadku wszystkich żądań korzystających z funkcji porównań pole comparison
jest automatycznie dodawane do wygenerowanego raportu. To pole zawiera nazwę porównania podanego w żądaniu.
Oto przykładowy fragment odpowiedzi zawierającej porównania:
{
"dimensionHeaders": [
{
"name": "comparison"
},
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "638572"
}
]
},
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "376578"
}
]
},
{
"dimensionValues": [
{
"value": "App traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "79527"
}
]
},
...
],
...
}