In diesem Dokument werden mehrere erweiterte Funktionen der Google Analytics Data API Version 1 beschrieben. Eine ausführliche Referenz zur API finden Sie in der API-Referenz.
Benutzerdefinierte Definitionen auflisten und Berichte erstellen
Mit der Data API können Berichte zu registrierten benutzerdefinierten Dimensionen und benutzerdefinierten Messwerten erstellt werden. Mit der Metadata API Method können Sie die API-Namen der registrierten benutzerdefinierten Definitionen Ihrer Property auflisten. Diese API-Namen können beispielsweise in Berichtsanfragen an die runReport-Methode verwendet werden.
In den folgenden Abschnitten finden Sie Beispiele für jeden Typ von benutzerdefinierter Definition. Ersetzen Sie in diesen Beispielen GA4_PROPERTY_ID
durch Ihre Property-ID.
Benutzerdefinierte Dimensionen auf Ereignisebene
Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Schritt 2:Suchen Sie die ereignisbezogene benutzerdefinierte Dimension, für die Sie Berichte aus der Antwort erstellen möchten. Wenn die Dimension nicht vorhanden ist, müssen Sie die Dimension registrieren.
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
Schritt 3:Benutzerdefinierte Dimension in eine Berichtsanfrage einfügen Hier sehen Sie eine Beispielanfrage an die Methode 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" }]
}
Benutzerdefinierte Dimensionen auf Nutzerebene
Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Schritt 2:Suchen Sie die benutzerdefinierte Dimension auf Nutzerebene, für die Sie Berichte aus der Antwort erstellen möchten. Wenn die Dimension nicht vorhanden ist, müssen Sie die Dimension registrieren.
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
Schritt 3:Benutzerdefinierte Dimension in eine Berichtsanfrage einfügen Hier sehen Sie eine Beispielanfrage an die Methode 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" }]
}
Benutzerdefinierte Messwerte auf Ereignisebene
Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Schritt 2:Suchen Sie den ereignisbezogenen benutzerdefinierten Messwert, für den Sie Berichte aus der Antwort erstellen möchten. Wenn der Messwert nicht vorhanden ist, müssen Sie ihn registrieren.
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Schritt 3: Fügen Sie den benutzerdefinierten Messwert in eine Berichtsanfrage ein. Hier sehen Sie eine Beispielanfrage an die Methode 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" }]
}
Messwerte zur Schlüsselereignisrate für ein Schlüsselereignis
Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Schritt 2:Ermitteln Sie den Messwert „Schlüsselereignisrate“ für ein wichtiges Ereignis, für das Sie Berichte aus der Antwort erstellen möchten. Wenn das Schlüsselereignis nicht vorhanden ist, müssen Sie es einrichten.
"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",
},
...
],
Schritt 3:Fügen Sie den Messwert „Schlüsselereignisrate“ in eine Berichtsanforderung ein. Hier sehen Sie eine Beispielanfrage an die Methode 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" }]
}
Durchschnittswerte für benutzerdefinierte Messwerte auf Ereignisebene
Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Schritt 2: Ermitteln Sie den ereignisbezogenen benutzerdefinierten Messwert-Durchschnitt, für den Sie Berichte aus der Antwort erstellen möchten. Wenn der Messwert nicht vorhanden ist, müssen Sie ihn registrieren.
"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"
},
...
],
Schritt 3:Fügen Sie den Durchschnitt des benutzerdefinierten Messwerts in eine Berichtsanfrage ein. Hier sehen Sie eine Beispielanfrage an die Methode 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" }]
}
Beispiele für Kohortenberichte
In Kohortenberichten wird eine Zeitreihe für die Nutzerbindung für die Kohorte erstellt. Eine ausführliche Dokumentation zu den einzelnen API-Feldern finden Sie in der REST-Referenz für „Kohortenspektive“.
Kohortenbericht erstellen
Hier ist ein Beispiel für einen Kohortenbericht:
- Die Kohorte besteht aus Nutzern mit einem
firstSessionDate
von2020-12-01
. Dies wird vomcohorts
-Objekt konfiguriert. Die Dimensionen und Messwerte in der Antwort auf den Bericht basieren nur auf den Nutzern der Kohorte. - Der Kohortenbericht enthält drei Spalten, die durch die Dimensions- und Messwertobjekte konfiguriert werden.
- Die Dimension „
cohort
“ ist der Name der Kohorte. - Die Dimension
cohortNthDay
ist die Anzahl der Tage seit2020-12-01
. - Der Messwert
cohortActiveUsers
ist die Anzahl der noch aktiven Nutzer.
- Die Dimension „
- Das
cohortsRange
-Objekt gibt an, dass der Bericht Ereignisdaten für diese Kohorte enthalten soll, die mit dem2020-12-01
beginnen und am2020-12-06
enden.- Wenn der Detaillierungsgrad von
DAILY
verwendet wird, wird aus Konsistenzgründen die DimensioncohortNthDay
empfohlen.
- Wenn der Detaillierungsgrad von
Die Berichtsanforderung für die Kohorte lautet:
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"
}
},
}
Hier ein Beispiel für eine Antwort auf diese Anfrage:
{
"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
}
Aus dieser Antwort folgt ein Diagramm für diesen Kohortenbericht. Aus diesem Bericht geht hervor, dass der größte Rückgang bei den aktiven Nutzern für diese Kohorte zwischen dem ersten und zweiten Tag liegt.
Mehrere Kohorten und Anteil der Nutzerbindung
Nutzergewinnung und -bindung sind Möglichkeiten, Ihre Website oder App zu optimieren. Kohortenberichte konzentrieren sich auf die Nutzerbindung. In diesem Beispiel zeigt der Bericht, dass sich die Nutzerbindung innerhalb von 4 Tagen innerhalb von zwei Wochen um 10% für diese Property verbessert hat.
Zum Erstellen dieses Berichts geben wir drei Kohorten an: die erste mit einem firstSessionDate
von 2020-11-02
, die zweite mit einem firstSessionDate
von 2020-11-09
und die dritte mit einem firstSessionDate
von 2020-11-16
. Da die Anzahl der Nutzer in Ihrer Property in diesen drei Tagen unterschiedlich ist, wird der Messwert für den Anteil der Nutzerbindung der Kohorte von cohortActiveUsers/cohortTotalUsers
verglichen, anstatt den direkten Messwert cohortActiveUsers
zu verwenden.
Die Berichtsanforderung für diese Kohorten lautet:
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"
}
},
}
Hier ein Beispiel für eine Antwort auf diese Anfrage:
{
"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
}
Aus dieser Antwort folgt ein Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht besagt, dass die Nutzerbindung von vier Tagen innerhalb von zwei Wochen um 10% gestiegen ist. Die spätere Kohorte mit firstSessionDate
von 2020-11-16
überschreitet die Kundenbindung der früheren Kohorte mit firstSessionDate
von 2020-11-02
.
Wöchentliche Kohorten und Verwendung von Kohorten mit anderen API-Funktionen
Um tägliche Abweichungen im Nutzerverhalten zu vermeiden, verwenden Sie wöchentliche Kohorten. In wöchentlichen Kohortenberichten bilden alle Nutzer mit firstSessionDate
in derselben Woche die Kohorte. Wochen beginnen am Sonntag und enden am Samstag. Außerdem wird in diesem Bericht die Kohorte unterteilt, um die Nutzer mit Aktivitäten in Russland mit denen mit Aktivitäten in Mexiko zu vergleichen. Bei diesem Segmentierungstyp werden die Dimension country
und ein dimensionFilter
verwendet, um nur die beiden Länder zu berücksichtigen.
Die Berichtsanforderung für diese Kohorten lautet:
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"
}
},
}
Hier ein Beispiel für eine Antwort auf diese Anfrage:
{
"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
}
Aus dieser Berichtsantwort folgt ein Diagramm dieses Kohortenberichts. Dem Bericht zufolge hält diese Property Nutzer mit Aktivitäten in Mexiko besser an als Nutzer mit Aktivitäten in Russland.
Vergleiche
Durch Vergleiche lassen sich Teilmengen von Daten gegenüberstellen. Sie können Vergleiche definieren, indem Sie das Feld comparisons
in einer Berichtsdefinition angeben. Die Vergleichsfunktion der Data API ähnelt der Funktion Vergleiche im Google Analytics-Frontend.
Eine ausführliche Dokumentation der einzelnen API-Felder finden Sie in der REST-Referenz zum Vergleich.
Vergleich erstellen
Sie können für jedes Dataset, das Sie vergleichen möchten, einen separaten Vergleich erstellen. Wenn Sie beispielsweise App- und Web-Daten vergleichen möchten, können Sie einen Vergleich für Android- und iOS-Daten und einen weiteren für Webdaten erstellen.
In diesem Beispielbericht werden zwei Vergleiche definiert. Hier werden die aktiven Nutzer nach Land aufgeschlüsselt.
Für den ersten Vergleich namens „App-Zugriffe“ wird inListFilter
verwendet, um der Dimension platform
die Werte „iOS“ und „Android“ zuzuordnen. Im zweiten Vergleich namens „Webtraffic“ wird anhand von stringFilter
die Dimension platform
mit „web“ abgeglichen.
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"
}
]
}
Bei allen Anfragen, bei denen die Vergleichsfunktion verwendet wird, wird dem generierten Bericht automatisch das Feld comparison
hinzugefügt. Dieses Feld enthält den Namen des Vergleichs, der in der Anfrage angegeben wurde.
Hier ist ein Beispiel-Snippet einer Antwort mit Vergleichen:
{
"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"
}
]
},
...
],
...
}