User Activity API

Mit der User Activity API kann ein Inhaber einer Google Analytics-Property alle Analytics-Messdaten abrufen, die mit einem einzelnen Nutzer verknüpft sind. Genauer gesagt ruft die API alle Messdaten ab, die mit einer bestimmten User-ID oder Client-ID verknüpft sind.

Anfrage zur Nutzeraktivität stellen

Um eine Anfrage zur Nutzeraktivität zu stellen, müssen Sie ein Anfrageobjekt mit den folgenden Feldern erstellen:

  1. Client-ID oder User-ID des Nutzers

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

    • Sie können den Account Explorer verwenden, um Ihre ID der Datenansicht zu ermitteln.

  3. Sie benötigen wahrscheinlich einen Zeitraum für die Daten, an denen Sie interessiert sind. Standardmäßig enthält die API Nutzeraktivitäten der letzten Woche.

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

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

Seitenumbruch

Die User Activity API nutzt Paginierung, um große Datensätze in mehrere Anfragen und Antworten aufzuteilen. Da die von der API zurückgegebenen Daten jedoch hierarchisch strukturiert sind, müssen vom Entwickler einige Besonderheiten berücksichtigt werden, um die Daten korrekt zu sortieren.

Der grundlegende Typ „Zeile“ für den Seitenumbruch ist die Aktivität. Da Nutzerdaten nach Sitzungen gruppiert sind, kann eine Seitengrenze innerhalb einer Sitzung auftreten und diese Sitzung kann Aktivitäten über mehrere Seiten umfassen.

Beispieldaten

Zu Demonstrationszwecken verwenden wir die folgenden Beispieldaten. In diesem Beispiel hat der Nutzer innerhalb von drei 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

Einzelne Seite

Wenn du eine Anfrage zur Nutzeraktivität mit einem pageSize von mindestens 18 stellst, werden alle Daten auf einer einzelnen Seite angezeigt 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

Bei einer Seitengröße von 5 werden diese Daten in vier Antwortseiten unterteilt:

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 sowie die beiden Sitzungen am 24. November auf der zweiten und dritten Seite aufgeteilt. Die Antworten sehen ungefähr 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 für den angeforderten Zeitraum eine große Datenmenge erfasst hat, gibt die API möglicherweise nur eine Teilmenge der Aktivitäten zurück. In diesem Fall gibt das Feld sampleRate an, welcher Anteil der Aktivitäten des Nutzers zurückgegeben wurde.

Stichprobenerhebung

Die Nutzerdaten werden auf Aktivitätsebene erfasst. Bei einer Abtastrate von 50% (0.5) ist beispielsweise die Hälfte der Nutzeraktivitäten in der Antwort enthalten.

Diese Aktivitäten werden willkürlich ausgewählt. Die API gibt keine Garantien für zufällige Stichproben oder dass die Stichprobenerhebung für die Aktivitäten im angegebenen Zeitraum proportional ist.

Stichprobenerhebung verhindern

Da diese API eine Sitzung einfach als eine Sammlung von Aktivitäten behandelt, werden Sitzungen, für die keine Aktivitäten im Stichprobensatz aufgeführt sind, nicht in der Antwort angezeigt. Wenn Sie eine umfassende Liste der Sitzungen oder Aktivitäten benötigen, können Sie Folgeanträge mit kürzeren Zeiträumen stellen.

Wenn Sie beispielsweise Daten von 2018-01-01 bis 2018-12-31 anfordern und die Antwort eine Abtastrate von 0.25 angibt, 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