User Activity API

Mit der User Activity API können Inhaber von Google Analytics-Properties alle Analytics-Messdaten abrufen, die mit einem einzelnen Nutzer verknüpft sind. Die API ruft alle Messdaten ab, die einer bestimmten User-ID oder Client-ID zugeordnet sind.

Hinweis: In der Referenz zur User-ID finden Sie eine kurze Einführung in Client-IDs, User-IDs und die Unterschiede zwischen ihnen.

Anfrage zur Nutzeraktivität stellen

Wenn Sie eine Anfrage zu einer Nutzeraktivität stellen möchten, müssen Sie ein Anfrageobjekt mit den folgenden Feldern erstellen:

1. Client-ID oder User-ID, die dem Nutzer zugeordnet ist

   • Unter Cookies und Nutzeridentifikation erfahren Sie, wie Sie diese Felder suchen.

2. Die ID einer Analytics-Datenansicht, die die mit dem Nutzer verknüpften Daten enthält.

   • Sie können den Konto-Explorer verwenden, um die Ansichts-ID zu ermitteln.

3. Sie benötigen wahrscheinlich einen Zeitraum für die Daten, an denen Sie interessiert sind, auch wenn dies nicht erforderlich ist. Standardmäßig werden in der API die Nutzeraktivitäten der letzten Woche aufgeführt.

Hinweis :In der Referenzdokumentation finden Sie eine vollständige Liste der Felder, die von dieser API akzeptiert werden, einschließlich Standardwerten für optionale Felder.

Beispielanfrage

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

Beispielantwort

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

Hinweis: In diesem Beispiel verwenden wir ..., um abgeschnittene Arrays anzugeben.

Sitzungen und Aktivitäten

Die Daten zur Nutzeraktivität werden nach Sitzung gruppiert. Jede Sitzung enthält allgemeine Informationen zur Sitzung wie Sitzungs-ID und Datum sowie eine Liste der Nutzeraktivitäten für diese Sitzung. Die Nutzeraktivitäten in einer Sitzung bestehen aus jedem „Treffer“, für den der Nutzer verantwortlich war. Dazu gehören beispielsweise Seitenaufrufe, E-Commerce-Ereignisse und benutzerdefinierte Ereignisse, die über gtag(...) oder ga(...) gesendet wurden.

Hinweis: Sitzungen können sich nicht über Datumsgrenzen erstrecken. Wenn die Verweildauer eines Nutzers auf Ihrer Website zwei verschiedene Tage umfasst, wird dies als zwei unterschiedliche Sitzungen an unterschiedlichen Tagen angezeigt. Weitere Informationen zur Definition einer Sitzung in Google Analytics finden Sie unter Wie wird eine Websitzung in Analytics definiert?

Hinweis: In der Activity-Referenz finden Sie eine genauere Definition einer Aktivität und die Unterschiede zu Treffern oder Ereignissen.

Seitenumbruch

Die User Activity API nutzt die Paginierung, um große Datensätze in mehrere Anfragen und Antworten aufzuteilen. Da die von der API zurückgegebenen Daten jedoch hierarchisch strukturiert sind, muss der Entwickler einige besondere Überlegungen berücksichtigen, um die Daten richtig zusammenzufassen.

Der grundlegende "Zeilen"-Typ für die Paginierung ist die Aktivität. Da Nutzerdaten nach Sitzung gruppiert sind, kann eine Seitengrenze innerhalb einer Sitzung auftreten und diese Sitzung kann Aktivitäten umfassen, die sich über mehrere Seiten erstrecken.

Wichtig :Seitengrenzen können innerhalb einer Sitzung auftreten.

Beispieldaten

Wir verwenden zu Demonstrationszwecken die folgenden Beispieldaten. In diesem Beispiel hat der Nutzer innerhalb von drei Tagen in sechs Sitzungen mit der Website interagiert.

Datum	Sitzungs-ID	Ereignislabel	Uhrzeit
2018-11-23	1	A	10:26
2018-11-23	1	B	10:32
2018-11-23	1	C	10:39
2018-11-23	2	A	18:04
2018-11-23	2	B	18:11
2018-11-23	2	C	18:26
2018-11-24	3	A	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	A	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	A	13:01
2018-11-25	6	B	13:09
2018-11-25	6	C	13:12
2018-11-25	6	D	13:23

Einzelne Seite

Wenn Sie eine Anfrage für eine Nutzeraktivität mit einem pageSize von mindestens 18 stellen, werden alle Daten auf einer einzigen Seite bereitgestellt und sehen in etwa so aus:

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

Hinweis: Viele Felder wurden der Einfachheit halber weggelassen. Dieses Beispiel soll nur die heirarchische Gruppierung von Aktivitäten und Sitzungen zeigen.

Mehrere Seiten

Wenn die Seitengröße jedoch 5 beträgt, werden diese Daten in vier Antwortseiten aufgeteilt:

Datum	Sitzungs-ID	Ereignislabel	Uhrzeit
Seite 1:
2018-11-23	1	A	10:26
2018-11-23	1	B	10:32
2018-11-23	1	C	10:39
2018-11-23	2	A	18:04
2018-11-23	2	B	18:11
Seite 2:
2018-11-23	2	C	18:26
2018-11-24	3	A	11:26
2018-11-24	3	B	11:29
2018-11-24	3	C	11:39
2018-11-24	3	D	11:42
Seite 3:
2018-11-24	4	A	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	A	13:01
Seite 4:
2018-11-25	6	B	13:09
2018-11-25	6	C	13:12
2018-11-25	6	D	13:23

Hinweis: Die Nutzeraktivitäten sind immer in einer sortierten Reihenfolge angeordnet. Die Grenzen zwischen den Seiten sind also niemals zufällig, sondern immer zwischen zeitlich benachbarten Sitzungen und Aktivitäten.

Beachten Sie, dass Sitzung 2 auf die erste und zweite Seite verteilt ist, während die beiden Sitzungen am 24. November auf die zweite und dritte Seite aufgeteilt werden. Die Antworten sehen in etwa so aus:

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

Stichprobenerhebung

Wenn ein Client eine große Datenmenge für den angeforderten Zeitraum angesammelt hat, gibt die API möglicherweise nur eine stichprobenbasierte Teilmenge von Aktivitäten zurück. In diesem Fall gibt das Feld sampleRate an, welcher Anteil der Aktivitäten des Nutzers zurückgegeben wurde.

So werden Stichproben erhoben

Die Nutzerdaten werden auf Aktivitätsebene erhoben. Bei einer Stichprobenrate von 50% (0.5) ist beispielsweise die Hälfte der Aktivitäten des Nutzers in der Antwort enthalten.

Diese Stichprobenaktivitäten werden willkürlich ausgewählt. Die API bietet weder Garantien für Zufallsstichproben noch, dass die Stichprobennahme proportional zu den Aktivitäten im angegebenen Zeitraum ist.

Stichprobenerhebung verhindern

Da diese API eine Sitzung einfach als Sammlung von Aktivitäten behandelt, werden Sitzungen, für die keine Aktivitäten im Stichprobensatz enthalten sind, nicht in der Antwort berücksichtigt. Wenn Sie eine umfassende Liste der Sitzungen oder Aktivitäten benötigen, stellen Sie Folgeanfragen für kürzere Zeiträume.

Wenn Sie beispielsweise Daten von 2018-01-01 bis 2018-12-31 anfordern und in der Antwort eine Stichprobenrate von 0.25 angegeben wird, teilen Sie den angeforderten Zeitraum in vier Teile auf, sodass jeder Teil hoffentlich etwa ein Viertel der Originaldaten enthält:

• 2018-01-01–2018-03-31
• 2018-04-01 nach 2018-06-30
• 2018-07-01 nach 2018-09-30
• 2018-10-01–2018-12-31

Hinweis: Aufgrund möglicher zufälliger Daten-Clustering werden diese Unterbereiche möglicherweise auch für Stichproben verwendet. Wenn beispielsweise die meisten Nutzerdaten im Zeitraum 2018-01-01 bis 2018-03-31 erfasst wurden, müssen Sie möglicherweise zusätzliche Anfragen stellen, bis Sie alle Daten ohne Stichproben erhalten haben.