User Activity API

Dzięki interfejsowi User Activity API właściciel usługi w Google Analytics może pobierać wszystkie analityczne dane pomiarowe powiązane z pojedynczym użytkownikiem. W szczególności interfejs API pobiera wszystkie dane pomiarowe powiązane z konkretnym identyfikatorem User-ID lub Client-ID.

Uwaga: krótkie wprowadzenie do identyfikatorów Client-ID i User ID oraz różnic między nimi znajdziesz w dokumentacji funkcji User-ID.

Wysyłanie żądania aktywności użytkownika

Aby utworzyć żądanie dotyczące aktywności użytkownika, utwórz obiekt żądania z użyciem tych pól:

1. Identyfikator Client-ID lub User ID powiązany z użytkownikiem.

   • Szczegółowe informacje o wyszukiwaniu tych pól znajdziesz w sekcji Pliki cookie i identyfikacja użytkownika.

2. Identyfikator widoku danych Analytics zawierający dane powiązane z użytkownikiem.

   • Identyfikator widoku możesz znaleźć w eksploratorze kont.

3. Chociaż nie jest to wymagane, prawdopodobnie będziesz potrzebować zakresu dat dla danych, które Cię interesują. Domyślnie interfejs API wyświetla aktywność użytkowników w minionym tygodniu.

Uwaga: pełną listę pól, które akceptuje ten interfejs API, w tym domyślne wartości pól opcjonalnych, znajdziesz w dokumentacji referencyjnej.

Przykładowe żądanie

POST https://analyticsreporting.googleapis.com/v4/userActivity:search

{
    "viewId": "9999999",
    "user": {
        "type": "CLIENT_ID",
        "userId": "1034600000.76425000000"
    },
    "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31",
    }
}

Przykładowa odpowiedź

{
    "sessions": [{
        "sessionId": "1539184430",
        "deviceCategory": "desktop",
        "platform": "Windows",
        "dataSource": "web",
        "sessionDate": "2018-10-10"
        "activities": [{
            "activityTime": "2018-10-10T08:13:50.555105Z",
            "source": "(direct)",
            "medium": "(none)",
            "channelGrouping": "Direct",
            "campaign": "(not set)",
            "keyword": "(not set)",
            "hostname": "shop.googlemerchandisestore.com",
            "landingPagePath": "/gpsmap",
            "activityType": "PAGEVIEW",
            "customDimension": [{
                "index": 1,
                "value": "(not set)"
            }, ...]
        }, ...]
    }, ...]
    "totalRows": 1000,
    "nextPageToken": "A6JGY3",
    "sampleRate": 1
}

Uwaga: w tym przykładzie do oznaczenia obciętych tablic używamy ....

Sesje i czynności

Dane dotyczące aktywności użytkowników są grupowane według sesji. Każda sesja zawiera ogólne informacje o sesji, np. jej identyfikator i datę, oraz listę działań użytkowników, które do niej doprowadziły. Na działania użytkownika w danej sesji składają się wszystkie „działania”, za które odpowiadał użytkownik. Obejmuje to m.in. odsłony, zdarzenia e-commerce i zdarzenia niestandardowe wysyłane przez gtag(...) lub ga(...).

Uwaga: sesje nie mogą obejmować zakresu dat. Jeśli czas spędzony przez użytkownika w witrynie obejmuje 2 różne dni, zostanie to przedstawione jako 2 różne sesje z różnymi datami. Więcej informacji o definicji sesji w Google Analytics znajdziesz w artykule Czym jest sesja internetowa w Analytics.

Uwaga: dokumentacja Activity zawiera dokładniejszą definicję działania i subtelny sposób odróżniania go od działania czy zdarzenia.

Podział na strony

Interfejs User Activity API używa podziału na strony, aby podzielić duże zbiory danych na wiele żądań i odpowiedzi. Jednak ze względu na to, że dane zwracane przez interfejs API mają strukturę hierarchiczną, deweloper musi zwrócić uwagę na pewne kwestie, aby prawidłowo je zebrać.

Podstawowym typem „wiersza” służącym do podziału na strony jest działanie. Dane użytkownika są grupowane według sesji, co oznacza, że granica strony może pojawić się w obrębie sesji, a sesja może mieć działania obejmujące wiele stron.

Ważne: granice stron mogą występować w sesji.

Przykładowe dane

Do celów demonstracyjnych użyjemy poniższych przykładowych danych. W tym przykładzie użytkownik wchodził w interakcję z witryną w 6 sesjach w ciągu 3 dni.

Data	Identyfikator sesji	Etykieta zdarzenia	Godzina
2018-11-23	1	O	10:26
2018-11-23	1	B	10:32
2018-11-23	1	C	10:39
2018-11-23	2	O	18:04
2018-11-23	2	B	18:11
2018-11-23	2	C	18:26
2018-11-24	3	O	11:26
2018-11-24	3	B	11:29
2018-11-24	3	C	11:39
2018-11-24	3	D	11:42
2018-11-24	4	O	23:50
2018-11-24	4	B	23:54
2018-11-25	5	C	00:02
2018-11-25	5	D	00:13
2018-11-25	6	O	13:01
2018-11-25	6	B	13:09
2018-11-25	6	C	13:12
2018-11-25	6	D	13:23

Pojedyncza strona

Jeśli wyślesz żądanie dotyczące aktywności użytkownika z elementem pageSize o wartości co najmniej 18, wszystkie dane zostaną dostarczone na jednej stronie i będą wyglądać mniej więcej tak:

POST https://analyticsreporting.googleapis.com/v4/userActivity:search

{
    "viewId": "9999999",
    "user": {
        "type": "CLIENT_ID",
        "userId": "1034600000.76425000000",
    },
    "dateRange": {
        "startDate": "2018-11-20",
        "endDate": "2018-11-30",
    },
    "pageSize": 100,
}

{
    "totalRows": 18,
    "sessions": [{
            "sessionId": "1",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T10:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T10:32:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T10:39:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:04:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T18:11:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T18:26:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "3",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T11:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T11:29:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-24T11:39:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-24T11:42:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "4",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T23:50:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T23:54:00",
                    "event": {"eventLabel": "B"}
                }]
        }, {
            "sessionId": "5",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T00:01:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T00:13:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:01:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-25T13:09:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-25T10:12:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T10:23:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

Uwaga: wiele pól zostało pominiętych ze względu na zwięzłość. Ten przykład pokazuje tylko hierarchiczne grupowanie działań i sesji.

Wiele stron

Jeśli jednak rozmiar strony to 5, dane zostaną podzielone na 4 strony odpowiedzi:

Data	Identyfikator sesji	Etykieta zdarzenia	Godzina
Strona 1:
2018-11-23	1	O	10:26
2018-11-23	1	B	10:32
2018-11-23	1	C	10:39
2018-11-23	2	O	18:04
2018-11-23	2	B	18:11
Strona 2:
2018-11-23	2	C	18:26
2018-11-24	3	O	11:26
2018-11-24	3	B	11:29
2018-11-24	3	C	11:39
2018-11-24	3	D	11:42
Strona 3:
2018-11-24	4	O	23:50
2018-11-24	4	B	23:54
2018-11-25	5	C	00:02
2018-11-25	5	D	00:13
2018-11-25	6	O	13:01
Strona 4:
2018-11-25	6	B	13:09
2018-11-25	6	C	13:12
2018-11-25	6	D	13:23

Uwaga: działania użytkowników są zawsze posortowane w kolejności posortowanej, co oznacza, że granica między stronami nigdy nie jest losowa. Zawsze pomiędzy sesjami i działaniami sąsiadujące z czasem.

Zwróć uwagę, że sesja 2 jest podzielona na pierwszą i drugą stronę, a 2 sesje z 24 listopada – na drugą i trzecią stronę. Odpowiedzi będą wyglądać mniej więcej tak:

{
    "totalRows": 18,
    "nextPageToken": "UGMGQS",
    "sessions": [{
            "sessionId": "1",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T10:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T10:32:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T10:39:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:04:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T18:11:00",
                    "event": {"eventLabel": "B"}
                }]
        }]
}

{
    "totalRows": 18,
    "nextPageToken": "1FKOME",
    "sessions": [{
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:26:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "3",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T11:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T11:29:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-24T11:39:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-24T11:42:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

{
    "totalRows": 18,
    "nextPageToken": "7S77H6",
    "sessions": [{
            "sessionId": "4",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T23:50:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T23:54:00",
                    "event": {"eventLabel": "B"}
                }]
        }, {
            "sessionId": "5",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T00:01:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T00:13:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:01:00",
                    "event": {"eventLabel": "A"}
                }]
        }]
}

{
    "totalRows": 18,
    "sessions": [{
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:09:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-25T10:12:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T10:23:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

Próbkowanie danych

Jeśli klient zgromadził już dużo danych w żądanym zakresie dat, interfejs API może zwrócić tylko próbkowany podzbiór aktywności. W takim przypadku pole sampleRate wskazuje, jaki odsetek aktywności użytkownika został zwrócony.

Jak próbkowane są dane

Dane użytkownika są próbkowane na poziomie aktywności. Na przykład: jeśli częstotliwość próbkowania wynosi 50% (0.5), odpowiedź będzie zawierać połowę aktywności użytkownika.

Te próbkowane aktywności są wybierane losowo. Interfejs API nie gwarantuje, że próbkowanie losowe jest losowe ani że jest ono proporcjonalne do aktywności w danym zakresie dat.

Zapobieganie próbkowaniu danych

Ten interfejs API traktuje sesję jako po prostu zbiór działań, więc żadne sesje, dla których nie wystąpiły żadne działania w próbkowanym zbiorze, nie pojawią się w odpowiedzi. Jeśli potrzebujesz pełnej listy sesji lub działań, wyślij kolejne prośby o krótsze zakresy dat.

Jeśli na przykład prosisz o dane z okresu od 2018-01-01 do 2018-12-31, a odpowiedź wskazuje na częstotliwość próbkowania 0.25, podziel żądany zakres dat na 4 części, tak aby każda część zawierała około jednej czwartej danych oryginalnych:

• Od 2018-01-01 do 2018-03-31
• Od 2018-04-01 do 2018-06-30
• Od 2018-07-01 do 2018-09-30
• Od 2018-10-01 do 2018-12-31

Uwaga: ze względu na możliwość losowego grupowania danych te podzakresy mogą być również próbkowane. Jeśli na przykład większość danych użytkownika pochodziła z zakresu dat 2018-01-01–2018-03-31, może być konieczne wysyłanie dodatkowych żądań, aż uzyskasz wszystkie niespróbkowane dane.