Erweiterte Anwendungsfälle

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-Methode können die API-Namen der registrierten benutzerdefinierten Definitionen Ihrer Property aufgelistet werden. 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 Conversion-Rate für eine einzelne Conversion

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 Messwert für die Conversion-Rate für eine Conversion, für die Sie Berichte aus der Antwort erstellen möchten. Ist das Conversion-Ereignis nicht vorhanden, müssen Sie es einrichten.

"metrics": [
...
    {
      "apiName": "sessionConversionRate:add_to_cart",
      "uiName": "Session conversion rate for add_to_cart",
      "description": "The percentage of sessions in which a specific conversion event was triggered",
    },
...
],

Schritt 3: Fügen Sie den Messwert für die Conversion-Rate 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": "sessionConversionRate: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 von 2020-12-01. Dies wird vom cohorts-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 seit 2020-12-01.
  • Der Messwert cohortActiveUsers ist die Anzahl der noch aktiven Nutzer.
• Das cohortsRange-Objekt gibt an, dass der Bericht Ereignisdaten für diese Kohorte enthalten soll, die mit dem 2020-12-01 beginnen und am 2020-12-06 enden.
  • Wenn der Detaillierungsgrad von DAILY verwendet wird, wird aus Konsistenzgründen die Dimension cohortNthDay empfohlen.

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 Kohorten mit anderen API-Funktionen verwenden

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.