Erweiterte Anwendungsfälle

In diesem Dokument werden einige 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 Berichtsabfragen für die Methode runReport verwendet werden.

In den folgenden Abschnitten finden Sie Beispiele für die einzelnen Typen von benutzerdefinierten 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 sie 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 Das Folgende ist ein Beispiel für 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 sie 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 Das Folgende ist ein Beispiel für 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 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:Benutzerdefinierten Messwert in eine Berichtsanfrage einfügen Das Folgende ist ein Beispiel für 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:Messwert „Schlüsselereignisrate“ in eine Berichtsanfrage einfügen Das Folgende ist ein Beispiel für 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 Method (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 durchschnittlichen ereignisbezogenen benutzerdefinierten Messwert, zu dem 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:Nehmen Sie den Durchschnitt des benutzerdefinierten Messwerts in eine Berichtsanfrage auf. Das Folgende ist ein Beispiel für 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

Im Kohortenbericht 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 sehen Sie ein Beispiel für einen Kohortenbericht:

  • Die Kohorte besteht aus Nutzern mit einem firstSessionDate von 2020-12-01. Sie wird durch das cohorts-Objekt konfiguriert. Die Dimensionen und Messwerte in der Antwort des Berichts basieren nur auf den Nutzern der Kohorte.
  • Im Kohortenbericht werden drei Spalten angezeigt. Dies wird durch die Dimensions- und Messwertobjekte 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 gibt die Anzahl der Nutzer an, die noch aktiv sind.
  • Das cohortsRange-Objekt gibt an, dass der Bericht Ereignisdaten für diese Kohorte ab dem 2020-12-01-Zeitraum bis zum 2020-12-06-Zeitraum enthalten soll.
    • Wenn die Granularität DAILY verwendet wird, empfiehlt sich die Dimension cohortNthDay, um die Konsistenz zu wahren.

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 ist eine Beispielantwort für einen Bericht:

{
  "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 Antwort folgt ein Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht ist, dass die Anzahl der aktiven Nutzer in dieser Kohorte zwischen dem ersten und dem zweiten Tag am stärksten abnimmt.

Visualisierung von Kohortennutzern im Zeitverlauf

Mehrere Kohorten und Nutzerbindungsanteil

Nutzergewinnung und ‑bindung sind Möglichkeiten, Ihre Website oder App zu optimieren. Kohortenberichte konzentrieren sich auf die Nutzerbindung. In diesem Beispiel sehen Sie, dass die Nutzerbindung nach 4 Tagen für diese Property im Laufe von zwei Wochen um 10% gestiegen ist.

Für diesen Bericht werden drei Kohorten festgelegt: 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 „Anteil der Nutzerbindung“ der Kohorte von cohortActiveUsers/cohortTotalUsers anstelle des direkten Messwerts cohortActiveUsers.

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 ist eine Beispielantwort für einen Bericht:

{
  "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 Antwort folgt ein Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht ist, dass die Nutzerbindung nach 4 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.

Diagramm mit mehreren Kohortenbindungsraten

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

Um die täglichen Schwankungen im Nutzerverhalten zu berücksichtigen, sollten Sie wöchentliche Kohorten verwenden. In wöchentlichen Kohortenberichten bilden alle Nutzer mit firstSessionDate in derselben Woche die Kohorte. Wochen beginnen am Sonntag und enden am Samstag. Auch in diesem Bericht wird die Kohorte aufgeteilt, um Nutzer mit Aktivitäten in Russland mit Nutzern mit Aktivitäten in Mexiko zu vergleichen. Für diese Aufteilung 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 ist eine Beispielantwort für einen Bericht:

{
  "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 Antwort auf den Bericht folgt ein Diagramm dieses Kohortenberichts. Laut diesem Bericht werden Nutzer mit Aktivität in Mexiko besser gebunden als Nutzer mit Aktivität 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 Feld comparisons in einer Berichtsdefinition angeben. Die Vergleichsfunktion der Data API ähnelt Vergleichen im Google Analytics-Frontend.

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

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 sehen Sie ein Beispiel für einen Bericht, 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 inListFilter verwendet, um die Dimension platform mit den Werten „iOS“ und „Android“ abzugleichen. Im zweiten Vergleich mit dem Namen „Web-Traffic“ wird 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, in denen die Vergleichsfunktion verwendet wird, wird das Feld comparison automatisch in den generierten Bericht eingefügt. Dieses Feld enthält den Namen des Vergleichs, der in der Anfrage angegeben wurde.

Hier sehen Sie ein Beispiel für einen Ausschnitt aus 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"
        }
      ]
    },

    ...

  ],

...

}