Komplexere Anwendungsfälle

In diesem Dokument werden mehrere erweiterte Funktionen der Google Analytics Data API v1 beschrieben. Eine detaillierte 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 Sie die API-Namen der registrierten benutzerdefinierten Definitionen Ihrer Property auflisten. Diese API-Namen können beispielsweise in Berichtsanfragen an die Methode runReport verwendet werden.

In den folgenden Abschnitten finden Sie Beispiele für die einzelnen Typen benutzerdefinierter Definitionen. Ersetzen Sie in diesen Beispielen GA_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/GA_PROPERTY_ID/metadata

Schritt 2: Suchen Sie in der Antwort nach der benutzerdefinierten Dimension auf Ereignisebene, für die Sie Berichte 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: Fügen Sie die benutzerdefinierte Dimension in eine Berichtsanfrage ein. Das folgende Beispiel zeigt eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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/GA_PROPERTY_ID/metadata

Schritt 2: Suchen Sie in der Antwort nach der benutzerdefinierten Dimension auf Nutzerebene, für die Sie Berichte 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: Fügen Sie die benutzerdefinierte Dimension in eine Berichtsanfrage ein. Das folgende Beispiel zeigt eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA_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/GA_PROPERTY_ID/metadata

Schritt 2: Suchen Sie in der Antwort nach dem benutzerdefinierten Messwert auf Ereignisebene, für den Sie Berichte erstellen möchten. Wenn der Messwert nicht vorhanden ist, müssen Sie den Messwert registrieren.

"metrics": [
...
    {
      "apiName": "customEvent:credits_spent",
      "uiName": "Credits Spent",
      "description": "An event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

Schritt 3: Nehmen Sie den benutzerdefinierten Messwert in eine Berichtsanfrage auf. Das folgende Beispiel zeigt eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

Messwerte für die 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/GA_PROPERTY_ID/metadata

Schritt 2: Suchen Sie in der Antwort nach dem Messwert „Schlüsselereignisrate“ für ein Schlüsselereignis, für das Sie Berichte 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: Nehmen Sie den Messwert „Schlüsselereignisrate“ in eine Berichtsanfrage auf. Das folgende Beispiel zeigt eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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/GA_PROPERTY_ID/metadata

Schritt 2: Suchen Sie in der Antwort nach dem gewünschten Durchschnitt des benutzerdefinierten Messwerts auf Ereignisebene, für den Sie Berichte 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. Das folgende Beispiel zeigt eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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 der Nutzerbindung für die Kohorte erstellt. Eine ausführliche Dokumentation zu den einzelnen API-Feldern finden Sie in der REST-Referenz für CohortSpec.

Kohortenbericht erstellen

Hier sehen Sie einen Beispiel-Kohortenbericht:

  • Die Kohorte besteht aus Nutzern mit einem firstSessionDate von 2020-12-01. Dies wird durch das Objekt cohorts konfiguriert. Die Dimensionen und Messwerte in der Berichtsantwort 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 Nutzer, die noch aktiv sind.
  • Das Objekt cohortsRange gibt an, dass der Bericht Ereignisdaten von 2020-12-01 bis 2020-12-06 für diese Kohorte enthalten soll.
    • Wenn eine Granularität von DAILY verwendet wird, wird die Dimension cohortNthDay aus Konsistenzgründen empfohlen.

Die Berichtsanfrage für die Kohorte lautet:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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"
    }
  },
}

Für diese Anfrage sieht eine Beispielantwort so aus:

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

Auf diese Berichtsantwort folgt ein Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht ist, dass der größte Rückgang der aktiven Nutzer für diese Kohorte zwischen dem ersten und dem zweiten Tag zu verzeichnen ist.

Visualisierung von Kohortennutzern im Zeitverlauf

Mehrere Kohorten und Anteil der Nutzerbindung

Nutzergewinnung und Nutzerbindung sind Möglichkeiten, Ihre Website oder App zu vergrößern. Kohortenberichte konzentrieren sich auf die Nutzerbindung. In diesem Beispiel zeigt der Bericht, dass die Nutzerbindung nach 4 Tagen für diese Property im Laufe von zwei Wochen um 10 % gestiegen ist.

Für diesen Bericht 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 an diesen drei Tagen unterschiedlich ist, vergleichen wir den Messwert für den Anteil der Nutzerbindung der Kohorte von cohortActiveUsers/cohortTotalUsers, anstatt den direkten Messwert cohortActiveUsers zu verwenden.

Die Berichtsanfrage für diese Kohorten lautet:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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"
    }
  },
}

Für diese Anfrage sieht eine Beispielantwort so aus:

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

Auf diese Berichtsantwort folgt ein Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht ist, dass die Nutzerbindung nach 4 Tagen im Laufe von zwei Wochen um 10 % gestiegen ist. Die spätere Kohorte mit firstSessionDate von 2020-11-16 übertrifft die Bindung der früheren Kohorte mit firstSessionDate von 2020-11-02.

Diagramm mit mehreren Kohortenbindungen

Wöchentliche Kohorten und Verwendung von Kohorten mit anderen API-Funktionen

Wenn Sie tägliche Abweichungen im Nutzerverhalten ausgleichen möchten, 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. In diesem Bericht wird die Kohorte außerdem aufgeteilt, um die Nutzer mit Aktivitäten in Russland mit den Nutzern mit Aktivitäten in Mexiko zu vergleichen. Für diese Aufteilung werden die Dimension country und ein dimensionFilter verwendet, um nur die beiden Länder zu berücksichtigen.

Die Berichtsanfrage für diese Kohorten lautet:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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"
    }
  },
}

Für diese Anfrage sieht eine Beispielantwort so aus:

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

Auf diese Berichtsantwort folgt ein Diagramm dieses Kohortenberichts. Laut diesem Bericht ist die Nutzerbindung in Mexiko besser als in Russland.

Diagramm mit Ländervergleichskohorten

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 Funktion „Vergleiche“ der Data API ähnelt den Vergleichen im Google Analytics-Frontend.

Eine ausführliche Dokumentation zu den einzelnen API-Feldern finden Sie in der REST-Referenz für Vergleiche.

Vergleich erstellen

Sie können für jeden Datensatz, den Sie vergleichen möchten, einen eigenen Vergleich erstellen. Um beispielsweise App- und Webdaten zu vergleichen, können Sie einen Vergleich für Android- und iOS-Daten und einen weiteren für Webdaten erstellen.

Hier ist ein Beispielbericht, in dem zwei Vergleiche definiert sind und aktive Nutzer nach Land aufgeschlüsselt zurückgegeben werden.

Im ersten Vergleich mit dem Namen „App-Traffic“ wird die inListFilter verwendet, um die Dimension platform mit den Werten „iOS“ und „Android“ abzugleichen. Beim zweiten Vergleich mit dem Namen „Webtraffic“ wird der stringFilter verwendet, um die Dimension platform mit „web“ abzugleichen.

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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, die die Vergleichsfunktion verwenden, wird das Feld comparison automatisch dem generierten Bericht 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"
        }
      ]
    },

    ...

  ],

...

}