User Activity API

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

Nutzeraktivitätsanfrage stellen

Um eine Nutzeraktivitätsanfrage zu stellen, erstellen Sie ein Anfrageobjekt mit den folgenden Feldern:

  1. Die dem Nutzer zugeordnete Client-ID oder User-ID

  2. Eine Analytics-Datenansichts-ID, die die mit dem Nutzer verknüpften Daten enthält.

    • Sie können den Konto-Explorer verwenden, um Ihre 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.

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
}

Sitzungen und Aktivitäten

Die Daten zur Nutzeraktivität werden nach Sitzung gruppiert. Jede Sitzung enthält allgemeine Informationen zur Sitzung, z. B. 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 Seitenaufrufe, E-Commerce-Ereignisse und benutzerdefinierte Ereignisse, die über gtag(...) oder ga(...) gesendet werden.

Seitenumbruch

Die User Activity API verwendet 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 anstellen, um die Daten korrekt zusammenzufassen.

Der grundlegende "Zeilentyp" für die Paginierung ist die Activity. Da Nutzerdaten nach Sitzung gruppiert werden, kann eine Seitengrenze innerhalb einer Sitzung auftreten und diese Sitzung kann Aktivitäten enthalten, die sich über mehrere Seiten erstrecken.

Beispieldaten

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

Datum Sitzungs-ID Ereignislabel Zeit
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

Einzelseite

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

Mehrere Seiten

Wenn Ihre Seitengröße jedoch fünf ist, werden diese Daten in vier Antwortseiten aufgeteilt:

DatumSitzungs-IDEreignislabelZeit
Seite 1:
2018-11-231A10:26
2018-11-231B10:32
2018-11-231C10:39
2018-11-232A18:04
2018-11-232B18:11
Seite 2:
2018-11-232C18:26
2018-11-243A11:26
2018-11-243B11:29
2018-11-243C11:39
2018-11-243D11:42
Seite 3:
2018-11-244A23:50
2018-11-244B23:54
2018-11-255C00:02
2018-11-255D00:13
2018-11-256A13:01
Seite 4:
2018-11-256B13:09
2018-11-256C13:12
2018-11-256D13:23

Sitzung 2 ist auf der ersten und zweiten Seite und die beiden Sitzungen am 24. November auf die zweite und dritte Seite aufgeteilt. 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 Nutzeraktivitäten zurückgegeben wurde.

Stichprobenerhebung

Die Nutzerdaten werden auf Aktivitätsebene erhoben. Bei einer Abtastrate 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 gibt weder Garantien für Zufallsstichproben noch dafür, dass die Stichprobenerhebung 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 im Stichprobensatz keine Aktivitäten 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 die Antwort eine Stichprobenrate von 0.25 anzeigt, teilen Sie den angeforderten Zeitraum in vier Teile auf, sodass jeder Teil voraussichtlich etwa ein Viertel der Originaldaten enthält:

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