Erweiterte Anwendungsfälle

In diesem Dokument werden mehrere erweiterte Funktionen der Google Analytics Data API v1 beschrieben. Eine detaillierte Referenz der 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 runReport verwendet werden.

In den folgenden Abschnitten finden Sie Beispiele für jeden Typ von benutzerdefinierter Definition. 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 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 finden 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: 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 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 finden 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: 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 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 finden 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 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 für die Schlüsselereignisrate für ein Schlüsselereignis, für den 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 für die Schlüsselereignisrate in eine Berichtsanfrage ein. Im Folgenden finden 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" }]
}

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 Durchschnittswert für den 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 Durchschnittswert für den benutzerdefinierten Messwert in eine Berichtsanfrage ein. Im Folgenden finden 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 einem firstSessionDate von 2020-12-01. Dies wird durch das Objekt cohorts konfiguriert. Die Dimensionen und Messwerte in der Berichtantwort basieren nur auf den Nutzern der Kohorte.
  • Der Kohortenbericht enthält drei Spalten. Dies wird durch die Objekte für Dimensionen und Messwerte konfiguriert.
    • Die Dimension cohort ist der Name der Kohorte.
    • Die Dimension cohortNthDay ist die Anzahl der Tage seit dem 2020-12-01.
    • Der Messwert cohortActiveUsers ist die Anzahl der noch aktiven Nutzer.
  • Das Objekt cohortsRange gibt an, dass der Bericht Ereignisdaten vom 2020-12-01 bis zum 2020-12-06 für diese Kohorte enthalten soll.
    • Wenn eine Granularität von DAILY verwendet wird, ist die Dimension cohortNthDay aus Konsistenzgründen empfehlenswert.

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
}

Aus dieser Berichtantwort ergibt sich das folgende Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht ist, dass der größte Rückgang bei den aktiven Nutzern für diese Kohorte zwischen dem ersten und zweiten Tag erfolgt.

Visualisierung von Kohortennutzern im Zeitverlauf

Mehrere Kohorten und Anteil der Nutzerbindung

Nutzerakquisition 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 Nutzerbindung nach vier Tagen für diese Property innerhalb von zwei Wochen um 10% verbessert hat.

Um diesen Bericht zu erstellen, 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 Anteil der Nutzerbindung der Kohorte 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
}

Aus dieser Berichtantwort ergibt sich das folgende Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht ist, dass die Nutzerbindung nach vier Tagen innerhalb von zwei Wochen um 10% gestiegen ist. Die spätere Kohorte mit dem firstSessionDate von 2020-11-16 übertrifft die Bindung der früheren Kohorte mit dem firstSessionDate von 2020-11-02.

Diagramm mit mehreren Kohortenbindungsraten

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

Um die täglichen Schwankungen im Nutzerverhalten zu entfernen, verwenden Sie wöchentliche Kohorten. In wöchentlichen Kohortenberichten bilden alle Nutzer mit einem firstSessionDate in derselben Woche die Kohorte. Wochen beginnen am Sonntag und enden am Samstag. In diesem Bericht segmentieren wir die Kohorte auch, um die Nutzer mit Aktivitäten in Russland mit Nutzern mit Aktivitäten in Mexiko zu vergleichen. Für diese Segmentierung wird 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
}

Aus dieser Berichtantwort ergibt sich das folgende Diagramm für diesen Kohortenbericht. Dieser Bericht zeigt, dass diese Property Nutzer mit Aktivitäten in Mexiko besser binden kann als Nutzer mit Aktivitäten in Russland.

Diagramm der Kohorten für den Ländervergleich

Vergleiche

Durch Vergleiche lassen sich Teilmengen von Daten gegenüberstellen. Sie können Vergleiche definieren, indem Sie das comparisons Feld in einer Berichtsdefinition angeben. Die Funktion „Vergleiche“ der Data API ähnelt den Vergleichen im Google Analytics-Frontend.

Eine detaillierte Dokumentation der einzelnen API-Felder finden Sie in der REST-Referenz für Comparison.

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.

Für den ersten Vergleich mit dem Namen „App-Traffic“ wird der inListFilter verwendet, um die Dimension platform mit den Werten „iOS“ und „Android“ abzugleichen. Für den zweiten Vergleich mit dem Namen „Web-Traffic“ 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 Funktion „Vergleiche“ verwenden, wird das Feld comparison automatisch zum generierten Bericht hinzugefügt. Dieses Feld enthält den Namen des in der Anfrage angegebenen Vergleichs.

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

    ...

  ],

...

}