Erweiterte Anwendungsfälle

In diesem Dokument werden mehrere erweiterte Funktionen der Google Analytics Data API v1 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 Methode der Metadaten-API 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 jeden benutzerdefinierten Definitionentyp. Ersetzen Sie in diesen Beispielen GA_PROPERTY_ID durch Ihre Property-ID.

Benutzerdefinierte Dimensionen auf Ereignisebene

Schritt 1:Rufen Sie die Methode der Metadaten-API 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 sie 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. Im Folgenden sehen Sie eine Beispielanfrage 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:Rufen Sie die Methode der Metadaten-API 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 sie 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. Im Folgenden sehen Sie eine Beispielanfrage 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:Rufen Sie die Methode der Metadaten-API 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 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. Im Folgenden sehen Sie eine Beispielanfrage 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 genau ein Schlüsselereignis

Schritt 1:Stellen Sie eine Abfrage an die Methode der Metadaten API mit Ihrer Property-ID.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Schritt 2:Suchen Sie den 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:Fügen Sie den Messwert „Schlüsselereignisrate“ in eine Berichtsanfrage ein. Im Folgenden sehen Sie eine Beispielanfrage 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" }]
}

Durchschnittliche benutzerdefinierte Messwerte auf Ereignisebene

Schritt 1:Rufen Sie die Methode der Metadaten-API 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 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. Im Folgenden sehen Sie eine Beispielanfrage 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 detaillierte Dokumentation der einzelnen API-Felder finden Sie in der REST-Referenz für CohortSpec.

Kohortenbericht erstellen

Hier ist ein Beispiel für einen Kohortenbericht:

  • Die Kohorte besteht aus Nutzern mit der firstSessionDate 2020-12-01. Diese wird vom cohorts-Objekt konfiguriert. Die Dimensionen und Messwerte in der Berichtsantwort basieren nur auf den Nutzern der Kohorte.
  • Der Kohortenbericht enthält drei Spalten, die über die Dimensionen 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 vom 2020-12-01 bis zum 2020-12-06 enthalten soll.
    • Wenn eine Detailebene von DAILY verwendet wird, wird die Dimension cohortNthDay aus Gründen der Einheitlichkeit 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"
    }
  },
}

Eine Beispielantwort für diese Anfrage wäre:

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

Nach dieser Berichtsantwort folgt ein Diagramm für diesen Kohortenbericht. Dieser Bericht zeigt beispielsweise, 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 Nutzerbindungsanteil

Die Nutzergewinnung und -bindung sind Möglichkeiten, Ihre Website oder App zu vergrößern. Kohortenberichte konzentrieren sich auf die Nutzerbindung. In diesem Beispiel zeigt der Bericht, dass sich die Bindung von Nutzern nach vier Tagen in dieser Property im Laufe von zwei Wochen um 10% verbessert hat.

Für diesen Bericht geben wir drei Kohorten an: die erste mit einer firstSessionDate von 2020-11-02, die zweite mit einer firstSessionDate von 2020-11-09 und die dritte mit einer firstSessionDate von 2020-11-16. Da sich die Anzahl der Nutzer in Ihrer Property in diesen drei Tagen unterscheidet, vergleichen wir den Messwert „Nutzerbindungsanteil“ 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"
    }
  },
}

Eine Beispielantwort für diese Anfrage wäre:

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

Nach dieser Berichtsantwort folgt ein Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht ist, dass die Nutzerbindung nach vier 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

Verwenden Sie wöchentliche Kohorten, um tägliche Schwankungen beim Nutzerverhalten zu berücksichtigen. 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 auch in Scheiben geschnitten, um die Nutzer mit Aktivitäten in Russland mit Nutzern mit Aktivitäten in Mexiko zu vergleichen. Bei dieser Aufschlüsselung 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"
    }
  },
}

Eine Beispielantwort für diese Anfrage wäre:

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

Nach dieser Berichtsantwort folgt ein Diagramm dieses Kohortenberichts. Laut diesem Bericht gelingt es der Property besser, Nutzer mit Aktivitäten in Mexiko als Nutzer mit Aktivitäten in Russland zu binden.

Diagramm mit Kohorten für Ländervergleiche

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 in der Google Analytics-Benutzeroberfläche.

Eine detaillierte Dokumentation der einzelnen API-Felder finden Sie in der REST-Referenz zum Vergleich.

Vergleich erstellen

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

Hier sehen Sie einen Beispielbericht, in dem zwei Vergleiche definiert und aktive Nutzer nach Land aufgeschlüsselt werden.

Beim ersten Vergleich mit dem Namen „App-Traffic“ wird die inListFilter verwendet, um die Dimension platform mit den Werten „iOS“ und „Android“ abzugleichen. Im zweiten Vergleich namens „Webzugriffe“ wird die 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, 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 ist.

Hier ist ein Beispiel für ein 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"
        }
      ]
    },

    ...

  ],

...

}